GithubHelp home page GithubHelp logo

csm-kb / fern-go Goto Github PK

View Code? Open in Web Editor NEW

This project forked from devdoshi/fern-go

0.0 0.0 0.0 2.01 MB

Generate Go models, clients, and server interfaces from your API definition.

License: MIT License

Shell 0.22% Go 99.60% Makefile 0.17%

fern-go's Introduction


header

Go Generator

Contributors Pulls-opened Pulls-merged

Discord

This repository contains the source for the Fern generators that produce Go artifacts:

  • fernapi/fern-go-sdk
  • fernapi/fern-go-model

The generator is written in Go and produces idiomatic code that feels hand-written and is friendly to read.

Fern handles transforming an API definition -- either an OpenAPI or Fern specification -- into Fern intermediate representation. IR is a normalized, Fern-specific definition of an API containing its endpoints, models, errors, authentication scheme, version, and more. Then the Go generator takes over and turns the IR into production-ready code.

Highlights

  • Fully typed. Your users will get great autocomplete and compile-time safety.
  • Dependency free. Built with the standard library, compatible with any net/http-flavored library.
  • Idiomatic. Incorporates an intuitive, Stripe-like package structure.
  • Open source. Star Fern on GitHub ⭐

What is Fern?

Fern is an open source toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.

Head over to the official Fern website for more information, or head over to our Documentation to dive straight in and find out what Fern can do for you!

Generating Go

This generator is used via the Fern CLI, by defining one of the aforementioned Go artifacts as a generator:

- name: fernapi/fern-go-sdk
  version: 0.9.0
  output:
    location: local-file-system
    path: ../../generated/go

By default, Fern runs the generators in the cloud.

Using local file generation

To run a generator on your local machine, use the --local flag for fern generate. This will run the generator locally in a Docker container, allowing you to inspect its logs and output. Read more.

When Fern is configured to generate code locally, it can write its output anywhere on the local filesystem. The Go generator needs to know where to resolve its import statements from, so you will either need to add an import path or module configuration to do so.

Import path

This is recommended if you plan to depend on the generated Go SDK from within your project, and NOT depend on it as a separate, published Go module.

You can generate the Go SDK code into a gen/go/api package with the following generators.yml configuration:

default-group: local
groups:
  local:
    generators:
      - name: fernapi/fern-go-sdk
        version: 0.4.0
        config:
          importPath: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>/generated/go
        output:
          location: local-file-system
          path: ../../generated/go

Note that you will need to update the <YOUR_ORGANIZATION> and <YOUR_REPOSITORY> placeholders with the relevant elements in your go.mod path.

In this case, the generated Go SDK uses the same go.mod path used by the rest of your Go module.

Module

This is recommended if you plan to distribute the generated Go SDK as a separate, published Go module.

Alternatively, you can generate the Go SDK code into a separate module (defined with its own go.mod) with the following generators.yml configuration:

default-group: local
groups:
  local:
    generators:
      - name: fernapi/fern-go-sdk
        version: 0.4.0
        config:
          module:
            path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
        output:
          location: local-file-system
          path: ../../generated/go

This configuration will generate a go.mod alongside the rest of the Go SDK code at the target output location. With this, import statements within the generated Go SDK are all resolved from the configured module path.

By default, the generated go.mod will be set to 1.13. You can override this behavior by specifying the version key like so:

default-group: local
groups:
  local:
    generators:
      - name: fernapi/fern-go-sdk
        version: 0.4.0
        config:
          module:
            path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
            version: "1.19"
        output:
          location: local-file-system
          path: ../../generated/go

Note that if you want to depend on the generated Go SDK locally (without distributing it as a separate Go module), and you use the module configuration option, you will need to modify your project's top-level go.mod to include a replace statement like so:

module github.com/your/module

require "github.com/your/sdk" v0.0.0
replace "github.com/your/sdk" v0.0.0 => "path/to/generated/sdk"

If you only plan to use the generated SDK within your own Go module, we recommend using the importPath configuration option described above.

Explicit Null

By default, it's impossible to send an explicit JSON null for optional parameters. You can opt-in to generating a generic Optional[T] type that can be used to distinguish between a nil value (nothing is sent), a non-nil value (the value is sent), and an explicit null (a null value is sent). This is particularly useful for PATCH endpoints.

The Optional and Null constructor functions will be included at the root of your module and can be used like so:

client := acmeclient.NewClient()
updatedFoo, err := client.Foo.Update(
  context.TODO(),
  &acme.UpdateFooRequest{
    Name: acme.Optional("example"),
    Tag:  acme.Null[string](),
  },
  // Serialized as {"name":"example","tag":null}
)

An example configuration is shown below:

default-group: local
groups:
  local:
    generators:
      - name: fernapi/fern-go-sdk
        version: 0.4.0
        config:
          enableExplicitNull: true
        output:
          location: local-file-system
          path: ../../generated/go

Note that this feature requires generics, so the generated go.mod will be upgraded to 1.18 (as opposed to 1.13).

Releases

All generator releases are published in the Releases section of the GitHub repository. You can directly use these version numbers in your generator configuration files.

For instance, if you want to use version 0.3.0 of the Go generator:

default-group: local
groups:
  local:
    generators:
      - name: fernapi/fern-go-sdk
        version: 0.3.0
        output:
          location: local-file-system
          path: ../../generated/go

Fern will handle the rest automatically.

Contributing

We greatly value community contributions. All the work on Fern generators happens right here on GitHub, both Fern developers and community contributors work together through submitting code via Pull Requests. See the contribution guidelines in CONTRIBUTING on how you can contribute to Fern!

fern-go's People

Contributors

amckinney avatar dannysheridan avatar dependabot[bot] avatar dsinghvi avatar csm-kb avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.