詰まったところ

oapi-codegen使ってみて遭遇した詰まりポイントのメモです

1. オプション指定はconfigファイルを用意して`-config`オプションを付けて実行するか`--old-config-style`つけてワンライナーにするかどちらかに統一する必要がある

以下は-configと-include-tagsを両方指定しているのでエラーになる

$ oapi-codegen -config config.yml -include-tags="Api" openapi.yml

=> error processing flags: flags --include-tags aren't supported in new config style, please use --old-config-style or update your configuration

configファイルを使う場合

config.yml

package: MyPackage
generate:
  models: true
output: models.gen.go
output-options:
  include-tags:
    - Api

コマンド

$ oapi-codegen -config config.yml openapi.yml

`--old-config-style`つけたてワンライナーで実行する場合

$ oapi-codegen --old-config-style \
  -generate=types \
  -package=MyPackage \
  -include-tags=Api \
  openapi.yaml > models.gen.go

2. 設定ファイルを書く際にソースコードを読む必要がある

READMEに記載の通り細かくドキュメント化されていないのでソースコードの中からパラメータの名前などを調べて記入する必要があった

config.yml

package: MyPackage
generate:
  models: true
output: models.gen.go
output-options:
  include-tags:
    - Api

参照したソースコード

https://github.com/deepmap/oapi-codegen/blob/master/pkg/codegen/configuration.go
https://github.com/deepmap/oapi-codegen/blob/master/cmd/oapi-codegen/oapi-codegen.go#L48

3. configファイルの場合にパラメーターが変わっている箇所がある

例えば、--old-config-styleの際にtypesとして指定する型情報はconfigファイルではmodelsになっていた

config.yml

package: MyPackage
generate:
  models: true
output: models.gen.go
output-options:
  include-tags:
    - Api

4. 階層化してスキーマ管理をしている場合に5階層以上ネストされているとエラーになる

以下のようなOASがある場合にエラーになる

post:
  tags:
    - Api
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/requests/params'
  responses:
    '200':
      description: "ok"

components:
  schemas:
    requests:
      params:
        type: object
        required:
          - name
        properties:
          name:
            type: string
            example: name

エラーメッセージ:

error generating code: error creating operation definitions: error generating body definitions: error generating request body definition: error turning reference (#/components/schemas/requests/params) into a Go type: unexpected reference depth: 5 for ref: #/components/schemas/requests/params local: true

対応としては$ref使っている場合はopenapi-generatorなどで1つのファイルにまとめてから、そのまとめたファイルをインプットにする

環境

$ oapi-codegen -version
github.com/deepmap/oapi-codegen/cmd/oapi-codegen
v1.12.3