Open API Specでコード生成する際の個人的チェックリスト

前提

• フロントエンドではopenapi-typescriptを利用している
• バックエンドではOepnAPI Generator(Spring)を利用している
• OpenAPI Specの記述にはredocly-cliを利用している

pathファイルのポイント

• tagsに記載した内容がコントローラー名になる
  • 複数名で開発している時にはコンフリクトに気をつける必要がある
• descriptionにはクライアントがどう利用するか、どういう結果が返ってくるかを記載している
• operationIdに記載した内容がメソッド名になる
  • なので冗長な名前はつけなくて良い
    • 例： UserController#getUserByIdとかはgetByIdとかにできる
  • ただしoperationIdは全体でユニークである必要がある
• parametersにはそのパラメータにどういう値をしているするとどういう結果が返ってくるか記載している

schemaファイルのポイント

• schemaに記載した内容がdtoのファイル名になるので、単独でみた時にわかるようにしている
• $refを使わずにschemaを指定した場合、titleの内容がDTOのクラス名になる
  • titleにはDTOのクラス名になってもいいよう英語で記載し、descriptionに日本語で記載する
• $refを使わずに別々のファイルで同じ内容のobjectを定義した場合、一方のファイルはもう一方のファイルで定義されたDTOを参照することがある
  • 例： user.yamlとsupport.yamlで同じ構造を持つpropertyとしてcommonを持っていた場合、生成されるDTOはUserCommonDto.javaになり、UserDto.javaとSupportDto.javaの両方からUserCommonDto.javaを参照する
• APIのレスポンスがNULLで返される場合にはnullableをつける（OpenAPI 3.0系の場合）が、nullableをつけたプロパティはOpenAPI Generator(Spring)でJsonNullable<>でラップされて扱いづらくなる
  • JsonNullableをつけないようにはOpenAPI GeneratorのopenApiNullableプロパティをfalseにする（デフォルトはtrue）
• requiredをつけないとopenapi-typescriptで生成される型定義ではundefinedを含むUNION型になる
  • springで生成されるDtoのコンストラクタでrequiredをつけたプロパティが含まれ、かつgetterにBean Validationの@NotNullがつくので実行時に落ちる
  • nullableとrequiredのどちらかだけつける

その他

• undefinedなプロパティもバックエンド側にはnullが入った状態で送ってくれる
  • openapi-typescriptがやってくれているのかSpringのjacksonがやってくれているのかまでは追っていない