Go tip of the week: 4 tools for generating REST APIs

No REST API without an OpenAPI documentation! OpenAPI enables users of your API service to generate client code in the languages they use. But managing your API server code and an OpenAPI spec simulaneously is time-consuming and error-prone.

Here are four options for cutting that effort in half, by either generating Go code from an API spec, or generating an API spec from Go code.

From OpenAPI spec to code

Usually, you'd want to write the spec for your API first and then generate the code from the spec. Why? Because an API requires both server and client code, and moreover, you might want to enable software written in other languages than Go to connect to your API.

Two of the four contenders are spec-to-code generators:

oapi-codegen/oapi-codegen: Generate Go client and server boilerplate from OpenAPI 3 specifications

oapi-codegen is the oldest of the four tools but still up to date with changes like the new net/http featuers in Go 1.22. A main goal of oapi-codegen is to make building a server a straightforward process. To achieve that goal, oapi-codegen supports popular server packages like Chi, Echo, Fiber, or Gin.

ogen-go/ogen: OpenAPI v3 code generator for go

ogen’s unique selling points include lack of reflection or empty interfaces in the generated code, as well as pointer-free handling of optional, nullable, and optional nullable fields, using generics-based wrappers instead.

From code to OpenAPI documentation

There are good reasons for writing Go code first and generating the OpenAPI spec from the code. A compelling advantage is that your Go code becomes the single source of truth. Moreover, you can use the language you are already familar with, instead of learning Yet Another Specification Language™.

These two Go frameworks support you with going from Go code to a generated OpenAPI spec:

go-fuego/fuego: Golang Fuego - web framework generating OpenAPI 3 spec from source code

Fuego is a web server framework. (Think “Gin”, “Chi”, or “Echo”.) All you do is write an API server with Fuego, and the final Fuego server then delivers a generated OpenAPI spec at /swagger/index.html. It's that simple. Fuego supports all net/http-compatible middleware.

Your First API - Huma

Huma neither promotes API-first nor code-first approaches. Rather, it's “Huma-first”. Sounds strange, but the idea is intriguing: You write an API code skeleton in Go, then Huma generates both the OpenAPI spec and the Go boilerplate for you. All that's left to you is implementing the handlers. Like Fuego, Huma serves the OpenAPI spec at a specific URL. Unlike Fuego, Huma is web framework agnostic and lets you use a router of your choice.

Whatever you choose, there is nothing to lose

All of the above tools and frameworks have tested and proven concepts, and while the philosophies and approaches differ, I'd reckon that you'd be able to write solid REST API apps with any of them. Large, multi-language projects surely want to go the API-spec-first route while pure Go projects may prefer using Go code as a starting point.

Whatever approach and tooling you choose, may the source be with you!