oapi-codegenを用いたスキーマ駆動開発

1. インストール

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

2. 事前準備

config.yaml

package: oapi
output: ./oapi/openapi.gen.go
generate:
  gin-server: true
  models: true
output-options:
  skip-prune: true

openapi.yaml

TODO: コード書く

3. 生成

oapi-codegen -config config.yaml openapi.yaml

4. 組み込み

handler.go

TODO: コード書く

main.go

import (
    "<生成したコードのパッケージ>/oapi"
    "github.com/gin-gonic/gin"
)

func main() {
    server := oapi.NewServer()
    r := gin.Default()
    oapi.RegisterHandlers(r, server)
    r.Run(:8080)
}

参考資料

• GitHub - oapi-codegen/oapi-codegen: Generate Go client and server boilerplate from OpenAPI 3 specifications
• What Is OpenAPI? | Swagger Docs
• oapi-codegen使ってみて遭遇した詰まりポイント #Go - Qiita
• oapi-codegenのx-go-type, x-go-type-name, x-go-nameの意味
• OpenAPI Generatorに適したOpenAPIの書き方 - ZOZO TECH BLOG

Appendix-1 どのモジュールを生成・利用するか

• サーバサイド開発においてはリクエスト/レスポンスのデータ構造のみ扱えばよい（typesで生成されるモジュール群）
• 主な理由は以下の通り:
  • APIサーバの実装は自前でやった方が細かい部分の調整が効くこと
  • oapi-codegenの生成コードが将来的に変化していく事への追従コストへの懸念があること
  • リクエスト/レスポンスのデータ構造の生成だけでも十分な生産性向上が見込めること