OpenAPI3.0 から Go のAPIクライアントコードを生成するライブラリ選定

結論

oapi-codegen/oapi-codegen と ogen-go/ogen がよさげ。

1ファイルのみの生成でミニマムにやりたいなら oapi-codegen/oapi-codegen、リクエストのクライアント検証や optional 型、gRPC っぽいインタフェースで扱いたいなら ogen-go/ogen っていう所感。

要件

必須

• OpenAPI3.0に対応していること
• GoのAPIクライアントコードを生成できること

推奨（＝選定観点）

• ①ライブラリとして信頼できること
• ②生成に要す時間が短いこと
• ③生成コードが必要最低限であること

候補

OpenAPITools/openapi-generator

①ライブラリとして信頼できること

• スター数は21k
• 1〜2ヶ月に一度はバージョンアップデートされ定期的にメンテナンスされている　（ただし、さまざまな言語の更新を含む）

②生成に要す時間が短いこと
計測していないが1秒以内だった

❯ docker run -v ${PWD}:/local openapitools/openapi-generator-cli:v7.7.0 generate -i /local/hoge/openapi.yaml -g go -o /local/hoge/
[main] INFO  o.o.codegen.DefaultGenerator - Generating with dryRun=false
[main] INFO  o.o.c.ignore.CodegenIgnoreProcessor - No .openapi-generator-ignore file found.
[main] INFO  o.o.codegen.DefaultGenerator - OpenAPI Generator: go (client)
[main] INFO  o.o.codegen.DefaultGenerator - Generator 'go' is considered stable.
[main] INFO  o.o.c.languages.AbstractGoCodegen - Environment variable GO_POST_PROCESS_FILE not defined so Go code may not be properly formatted. To define it, try `export GO_POST_PROCESS_FILE="/usr/local/bin/gofmt -w"` (Linux/Mac)
[main] INFO  o.o.c.languages.AbstractGoCodegen - NOTE: To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI).
# 中略
[main] INFO  o.o.codegen.TemplateManager - writing file /local/hoge/.openapi-generator/FILES
################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
################################################################################

③生成コードが必要最低限であること
APIクライアントプロジェクトとして成り立つコードが生成されるため要件にはそぐわない

.
|--.gitignore
|--.openapi-generator
|--.openapi-generator-ignore
|  |--FILES
|  |--VERSION
|--.travis.yml
|--README.md
|--api
|  |--openapi.yaml
|--client.go
|--configuration.go
|--docs
|  |-- # 中略
|--git_push.sh
|--go.mod
|--go.sum
|-- # 中略
|--response.go
|--test
|  |-- # 中略
|--utils.go

oapi-codegen/oapi-codegen

①ライブラリとして信頼できること

• スター数は5.8k
• 数ヶ月に一度はバージョンアップデートされ定期的にメンテナンスされている

②生成に要す時間が短いこと
計測していないが1秒以内だった

❯ go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.3.0
go: downloading github.com/oapi-codegen/oapi-codegen/v2 v2.3.0
go: downloading github.com/getkin/kin-openapi v0.124.0
go: downloading golang.org/x/text v0.15.0
go: downloading golang.org/x/tools v0.21.0
go: downloading github.com/invopop/yaml v0.2.0
go: downloading github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826
go: downloading github.com/go-openapi/jsonpointer v0.20.2
go: downloading github.com/perimeterx/marshmallow v1.1.5
go: downloading github.com/go-openapi/swag v0.22.8
go: downloading github.com/mailru/easyjson v0.7.7
go: downloading github.com/josharian/intern v1.0.0
go: downloading golang.org/x/mod v0.17.0

❯ oapi-codegen -config cfg.yaml hoge/openapi.yaml

cfg.yaml

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

model のみであれば下記

cfg.yaml

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

③生成コードが必要最低限であること
指定したファイルのみ

|--client.gen.go

ogen-go/ogen

①ライブラリとして信頼できること

• スター数は1.2K
• 1〜2ヶ月に一度はバージョンアップデートされ定期的にメンテナンスされている

②生成に要す時間が短いこと
計測していないが1秒以内だった

❯ go install github.com/ogen-go/ogen/cmd/ogen@v1.3.0
go: downloading github.com/ogen-go/ogen v1.3.0
go: downloading github.com/go-faster/errors v0.7.1
go: downloading github.com/go-faster/yaml v0.4.6
go: downloading go.uber.org/zap v1.27.0
go: downloading golang.org/x/exp v0.0.0-20230725093048-515e97ebf090
go: downloading go.uber.org/multierr v1.11.0
go: downloading github.com/go-faster/jx v1.1.0
go: downloading github.com/fatih/color v1.17.0
go: downloading golang.org/x/sync v0.8.0
go: downloading golang.org/x/tools v0.24.0
go: downloading github.com/ghodss/yaml v1.0.0
go: downloading github.com/dlclark/regexp2 v1.11.4
go: downloading golang.org/x/text v0.17.0
go: downloading golang.org/x/sys v0.23.0
go: downloading golang.org/x/net v0.28.0
go: downloading github.com/segmentio/asm v1.2.0
go: downloading golang.org/x/mod v0.20.0

❯ ogen -clean -package hoge -config cfg.yaml -target . openapi.yaml

cfg.yaml

generator:
  features:
    enable:
      - 'paths/client'
      - 'debug/example_tests'
    disable_all: true

③生成コードが必要最低限であること

.
|--oas_cfg_gen.go
|--oas_client_gen.go
|--oas_faker_gen.go
|--oas_interfaces_gen.go
|--oas_json_gen.go
|--oas_request_encoders_gen.go
|--oas_response_decoders_gen.go
|--oas_schemas_gen.go
|--oas_test_examples_gen_test.go
|--oas_validators_gen.go

go-swagger/go-swagger

OpenAPI3.0未対応