The Bolg

Back to coding blogs 🧏🏾‍♂️

Introduction

this page documents how one adds openapi models and yaml to their repo

Pre requisites

The pre req will be having some form of API that you have already created. for me, its my forever WIP book tracking application

I create a new folder to house my spec like this

└── codegen/
    ├── generate.go
    └── cfg.yaml
    └── spec.yaml

spec.yaml

this file will be the openapi spec that you will need to come up with, (or just ask claude code to generate for you based on your repo)

here is a sample

openapi: 3.0.3
info:
  title: BookTrackr API
  description: A book tracking application API that allows users to manage their reading progress
  version: 1.0.0
  contact:
    name: API Support
servers:
  - url: http://localhost:8080
    description: Development server

components:
  securitySchemes:
    SessionAuth:
      type: apiKey
      in: cookie
      name: session_id
    
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique user identifier
        username:
          type: string
          description: Username
      required:
        - id
        - username

    Book:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique book identifier
        isbn:
          type: string
          description: Book ISBN
        title:
          type: string
          description: Book title
        description:
          type: string
          description: Book description
        author:
          type: string
          description: Book author
        image_url:
          type: string
          format: uri
          description: URL to book cover image
      required:
        - id
        - isbn
        - title
        - description
        - author
        - image_url

    UserBook:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Book ID
        isbn:
          type: string
          description: Book ISBN
        title:
          type: string
          description: Book title
        description:
          type: string
          description: Book description
        author:
          type: string
          description: Book author
        image_url:
          type: string
          format: uri
          description: URL to book cover image
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Reading progress percentage
        start_date:
          type: string
          description: Date when reading started
        finish_date:
          type: string
          description: Date when reading finished
        rating:
          type: integer
          minimum: 1
          maximum: 5
          description: User rating for the book
        review:
          type: string
          description: User review of the book
      required:
        - id
        - isbn
        - title
        - description
        - author
        - image_url
        - progress
        - start_date
        - finish_date
        - rating

    GoogleBooksVolume:
      type: object
      description: Google Books API volume response
      additionalProperties: true

    JSONResponse:
      type: object
      properties:
        message:
          type: string
          description: Response message
        data:
          oneOf:
            - type: object
            - type: array
            - type: string
            - type: number
            - type: boolean
          description: Response data
        error:
          type: string
          description: Error message if any
      required:
        - message

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error

    RegisterRequest:
      type: object
      properties:
        username:
          type: string
          description: Desired username
        password:
          type: string
          format: password
          description: User password
      required:
        - username
        - password

    LoginRequest:
      type: object
      properties:
        username:
          type: string
          description: Username
        password:
          type: string
          format: password
          description: User password
      required:
        - username
        - password

    CreateBookRequest:
      type: object
      properties:
        isbn:
          type: string
          description: Book ISBN
        title:
          type: string
          description: Book title
        description:
          type: string
          description: Book description
        author:
          type: string
          description: Book author
        image_url:
          type: string
          format: uri
          description: URL to book cover image
      required:
        - isbn
        - title
        - description
        - author
        - image_url

cfg.yaml

this config is how the generated structs based on the yaml above is outputted in the repo

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: generated
output: ../generated/models.gen.go
generate:
  models: true

generate.go

lastly, this file will house the go tool that converts the yaml into generated structs for the application to consume

//go:generate go tool oapi-codegen -config cfg.yaml openapi.yaml

you can regen the structs with

go generate  ./...

or, run the example same line above