Swagger/OpenAPI Generation for Go (Golang): go-swagger and oapi-codegen

Swagger/OpenAPI Generation for Go (Golang): go-swagger and oapi-codegen

Developing modern web services in Go requires a strict API specification. OpenAPI (formerly known as Swagger) is a standard for describing RESTful interfaces that allows you to automate the creation of clients, servers, and documentation. In the Go ecosystem, there are two key tools for generating code from OpenAPI specifications: go-swagger and oapi-codegen. In this article, we will thoroughly examine both approaches, their installation, and practical application.

What is OpenAPI and why generate code?

OpenAPI Specification (OAS) is a file format (usually YAML or JSON) that describes the endpoints, parameters, data types, and response schemas of your API. Instead of manually writing handlers, models, and validation, you can:

• Generate server code with routes and middleware.
• Generate a client SDK for other services.
• Automatically update documentation (Swagger UI).
• Avoid desynchronization between the specification and implementation.

Tool #1: go-swagger

go-swagger is a powerful but heavier tool that supports not only generation but also specification validation. It is ideal for complex projects with versioning.

Installing go-swagger

# Installation via go install (Go 1.17+)go install github.com/go-swagger/go-swagger/cmd/swagger@latest

# Verify installationswagger version

Generating a server from a specification

Suppose we have a file api.yaml:

openapi: "3.0.0"info:  title: Pet Store  version: "1.0.0"paths:  /pets:    get:      summary: List all pets      operationId: listPets      responses:        '200':          description: A list of pets          content:            application/json:              schema:                type: array                items:                  $ref: '#/components/schemas/Pet'components:  schemas:    Pet:      type: object      properties:        id:          type: integer        name:          type: string

Run server generation:

swagger generate server -f api.yaml -A petstore -t ./gen

After execution, the ./gen folder will contain:

• restapi/ — handlers and routes.
• models/ — data structures (Pet, Error, etc.).
• cmd/ — application entry point.

Example handler implementation

package restapi

import (    "net/http"    "petstore/gen/models"    "petstore/gen/restapi/operations")

func configureAPI(api *operations.PetstoreAPI) http.Handler {    api.ListPetsHandler = operations.ListPetsHandlerFunc(        func(params operations.ListPetsParams) middleware.Responder {            pets := []*models.Pet{                {ID: 1, Name: "Buddy"},                {ID: 2, Name: "Milo"},            }            return operations.NewListPetsOK().WithPayload(pets)        },    )    return api.Serve(nil)}

Tool #2: oapi-codegen

oapi-codegen is a modern, lightweight, and very fast generator from the DeepMap team. It supports OpenAPI 3.0 and focuses on minimalism. Recommended for new projects.

Installing oapi-codegen

go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest

Generating types and server

Use the same specification api.yaml. Run:

oapi-codegen -generate types,server -package petstore api.yaml > petstore.gen.go

The -generate flag allows you to choose what to generate:

• types — Go str