(完了)コード生成ツールの選択

[yamamoto-febc]

Go向けのコード生成ツールとして以下のようなものがある。

• https://github.com/OpenAPITools/openapi-generator
• https://github.com/deepmap/oapi-codegen

しかし、どちらを利用してもコンパイルエラーが出る。どう対応していくか?

[yamamoto-febc]

openapi-generatorの場合: コード生成自体ができない

$ docker run -it --rm -v $PWD:$PWD -w $PWD openapitools/openapi-generator-cli:latest generate -i definitions/swagger.json -g go -o fff/
Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 2, Warning count: 1
Errors: 
	-attribute paths.'/servers/{server_id}/ports/{port_id}/assign_network/'(post).requestBody.content.'application/json'.schema.default is not of type `array`
	-attribute paths.'/servers/{server_id}/port_channels/{port_channel_id}/configure_bonding/'(post).requestBody.content.'application/json'.schema.default is not of type `array`
Warnings: 
	-attribute paths.'/servers/{server_id}/ports/{port_id}/assign_network/'(post).requestBody.content.'application/json'.schema.default is not of type `array`
	-attribute paths.'/servers/{server_id}/port_channels/{port_channel_id}/configure_bonding/'(post).requestBody.content.'application/json'.schema.default is not of type `array`

	at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:546)
	at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:573)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:433)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

oapi-codegenの場合: コード生成はできるがコンパイルエラーとなる

$ oapi-codegen -generate=types,client -package phy -o phy_gen.go definitions/swagger.json
$ make go imports
$ make test

# github.com/sacloud/libphy
./phy_gen.go:909:13: undefined: Generic401ErrorCode
./phy_gen.go:3354:14: undefined: N401ErrorCode
./phy_gen.go:3389:14: undefined: N401ErrorCode
./phy_gen.go:3428:14: undefined: N401ErrorCode
./phy_gen.go:3463:14: undefined: N401ErrorCode
./phy_gen.go:3501:14: undefined: N401ErrorCode
./phy_gen.go:3537:14: undefined: N401ErrorCode
./phy_gen.go:3590:14: undefined: N401ErrorCode
./phy_gen.go:3624:14: undefined: N401ErrorCode
./phy_gen.go:3662:14: undefined: N401ErrorCode
./phy_gen.go:3662:14: too many errors
make: *** [test] Error 2

[yamamoto-febc]

openapi-generatorの場合、arrayに対してdefault: null指定がある箇所でエラーとなっている。
該当部分をdefault: []のように修正すればコード生成自体は可能。

[yamamoto-febc]

oapi-codegenの場合、generic_401などでのネストしたスキーマ定義部を"$ref"を使う形に書き換えると動く

# 変更前
  schemas:
    generic_401:
      description: 未ログイン
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                description: HTTPステータスコード
                example: 401 Unauthorized
              error_code:
                type: string
                enum:
                  - unauthorized
                description: エラー内容を示す簡潔な識別子
              error_msg:
                type: string
                description: 人間のためのエラーメッセージ
                example: error-unauthorized

# 変更後
  schemas:
    # generic_401から切り出し
    problem_details_401:
      type: object
      properties:
        status:
          type: string
          description: HTTPステータスコード
          example: 401 Unauthorized
        error_code:
          type: string
          enum:
            - unauthorized
          description: エラー内容を示す簡潔な識別子
        error_msg:
          type: string
          description: 人間のためのエラーメッセージ
          example: error-unauthorized

    generic_401:
      description: 未ログイン
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_details_401'

[yamamoto-febc]

oapi-codegen向けにスキーマを切り出していく場合3ヶ所の修正が必要

• generic_401
• /servers/{server_id}/raid_status/のraid_status
• /servers/{server_id}/power_status/のpower_status

[yamamoto-febc]

oapi-codegen向けにスキーマを切り出していく方法の方が各定義の意味を変えずに修正できるため望ましい。
フィードバックしてそもそもの定義を修正してもらった方が良さそう。

[yamamoto-febc]

定義と違うデータ型が返されるケースがありそう。

// 試しに書いてみたコードでのエラー
json: cannot unmarshal number into Go struct field .servers.spec.cpu_clock_speed of type string

定義部

            cpu_clock_speed:
              type: string
              description: CPUクロック数(GHz)
              example: '2.1'

実際のレスポンス:

        "cpu_clock_speed": 3,

[yamamoto-febc]

現時点では https://github.com/deepmap/oapi-codegen を採用しつつ、定義の書き方や誤りについてフィードバックして根本から解決していく。

[yamamoto-febc]

#5 で対応