Generating Go Code from OpenAPI Specification

A quick and practical walkthrough for developers who want to generate type-safe Go code directly from OpenAPI specs.

A step-by-step look at generating Go code from OpenAPI specification#

Introduction#

OpenAPI to Go code generation flow

As a back-end developer working on a rapidly evolving project, I wanted to explore a faster approach to API development. That’s when I discovered oapi-codegen, a Go tool that automatically generates API code from an OpenAPI Specification (OAS) file.

After experimenting with it and seeing how cleanly it integrates into real-world projects, I decided to write this post to walk through the end-to-end process of generating Go code with oapi-codegen.

By the end of this guide, you’ll know how to:

Install and use oapi-codegen
Understand OpenAPI’s structure
Generate clean, type-safe Go code
Integrate it into your own API workflow

Prerequisites#

To follow along, you’ll need:

Go 1.16+
A basic understanding of Go syntax and modules
Familiarity with REST APIs
Some prior exposure to OpenAPI concepts (helpful but not mandatory)

What is OpenAPI Specification?#

According to the official OpenAPI documentation:

“The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.”

In simpler terms, OpenAPI is a blueprint for APIs — it describes endpoints, request/response formats, authentication, and data models — all in a structured YAML or JSON file.

That means both humans and machines can interpret your API consistently.

Why Opt for OpenAPI?#

Design-first approach: Define the API contract before writing code, ensuring clarity and shared understanding.
Team independence: Backend and frontend teams can work in parallel using mock servers.
Auto-generated documentation: Tools like Swagger UI can instantly visualize the spec.
Code generation: You can generate both server and client code in multiple languages.

Creating the Project#

Navigate to the folder where you want to create a sample project.
Start the project’s module using the go mod init command in the terminal:
```
go mod init github.com/MikeMwita/article
```

Writing OpenAPI document#

This is a sample of the OpenAPI specification file we will use to generate the documentation.

openapi: 3.0.3
info:
  title: FinanceAPP
  description: FinanceAPP
  version: 2022-04-01
servers:
  - url: 'http://localhost:9090/v1'
    description: 'Local'
paths:
  /signup:
    summary: Signup for users to get account
    description:  User account signup
    post:
      summary: A POST request to sign up for an account
      security: []
      operationId: signUp
      tags:
        - Signup
      description: sign up post
      requestBody:
        description: signup request object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: full user name
                  type: string
                  example: john doe
                email:
                  type: string
                  description: valid email
                  example: john.doe@example.com
                password:
                  type: string
                  description: strong password
                  example: secureP@ssword
                  minLength: 6
                  maxLength: 16
                confirm_password:
                  type: string
                  example: secureP@ssword
                  minLength: 6
                  maxLength: 16
              required:
                - name
                - password
                - email
                - confirm_password
      responses:
        '200':
          description: succesfully signed up
          content:
            application/json:
              schema:
                properties:
                  name:
                    type: string
                    example: Joe doe
                  email:
                    type: string
                    example: john.doe@example.com
        default:
          description: error
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  error:
                    type: string
tags:
  - name: Signup
    description: signup description

You can install the Gherkin extension for YAML files in your preferred IDE’s marketplace. This will allow you to write better and structure your OpenAPI document effectively.

_Initially posted on [medium.com](https://medium.com/@MikeMwita/generating-go-code-from-openapi-specification-document-ae225e49e970)_