OpenAPI

Document endpoints with OpenAPI 3, generate clients, validate schemas, and publish Swagger UI.

8 min readBuilding Backend ApplicationsBuild

Why OpenAPI

OpenAPI is a specification for documenting REST APIs. It provides a machine-readable contract that tools can use to generate clients, validate requests, test endpoints, and publish interactive documentation.

OpenAPI Structure

OpenAPI 3.0 skeleton


openapi: "3.0.3"
info:
  title: "My API"
  version: "1.0.0"
  description: "Backend API for My Application"
servers:
  - url: "http://localhost:8080"
    description: "Development"
  - url: "https://api.example.com"
    description: "Production"
paths:
  /users:
    get:
      summary: "List users"
      operationId: listUsers
      responses:
        "200":
          description: "User list"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string

OpenAPI is YAML or JSON. It defines info, servers, paths (endpoints), and components (schemas, parameters, responses). Tools parse this to generate documentation and code.

Defining Endpoints

Full endpoint definition


paths:
  /users/{id}:
    get:
      summary: "Get a user by ID"
      operationId: getUser
      tags: ["Users"]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: "User found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - bearerAuth: []

Each path operation defines parameters, request body, responses, and security. Tags group endpoints in documentation. OperationId is used for client generation.

Request/Response Schemas

Reusable schema components


components:
  schemas:
    User:
      type: object
      required: [id, email, name]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 255
        role:
          type: string
          enum: [admin, user, viewer]
        created_at:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required: [email, name, password]
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        password:
          type: string
          minLength: 8

    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string

Define schemas as reusable components. Use $ref to reference them in endpoints. This ensures consistency and reduces duplication.

Code Generation

Generate Go client from OpenAPI


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

# Generate Go client
oapi-codegen -generate types -o types.go -package api spec.yaml
oapi-codegen -generate client -o client.go -package api spec.yaml

# Generate server stubs
oapi-codegen -generate chi-server -o server.go -package api spec.yaml

Code generation produces type-safe Go code from your OpenAPI spec. Types, clients, and server stubs are all generated. Your handlers implement the generated interfaces.

Swagger UI

Goserving-swagger-ui.go

22 linesLn 1, Col 1Go

Swagger UI provides interactive API documentation. Developers can test endpoints directly from the browser. Serve it at /swagger/ in development.

Generate OpenAPI from code

Use swaggo/swag to generate OpenAPI specs from Go annotations. Add comments to your handlers and run swag init to produce the spec. This keeps documentation in sync with code.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 3 · Build

API Design & gRPC