ReadableなOpenAPI定義ファイルを書く - ドワンゴ教育サービス開発者ブログ

一行要約 はじめに Readable OpenAPIとは? 既存ルールの不満点 不満点1: 標準仕様外の分割を行っている 不満点2: ディレクトリ階層が深い 不満点3: 1つのAPI定義を参照する際にたくさんのファイルを参照する必要がある 不満点4: コンポーネントスキーマの同一性が不明瞭 新ルールで工夫した点 工夫1: operationIdと対応したパス定義のファイル名を採用し、フラットなディレクトリ構造を実現した 工夫2: パス定義ファイルに含まれる情報量を増やした 工夫3: 再利用性を重視したcomponent定義 できなかったこと、やらなかったこと、やりたいこと 定義ファイルのhttpメソッドごとの分割ができなかった ルートの定義ファイルにcomponentディレクティブを置かなかった exampleの定義は余力があればやりたい おわりに We are hiring! 脚注 一行

[hmiyado]

OpenAPI の定義はいろいろと流派がありますが、「yamlのままで読みやすい」にフォーカスしたバックエンドチームの取り組みについて記事を書いていただきました

[aquarickn]

Yamlを管理できる人は限られる職人技に近いので、stoplight を使ってる

[strawberryhunter]

弊社ではOpenAPIのYAMLは人間が書いたり読んだりするものではないという結論に至った。

[for-my-internet-demo]

確かに正直特定の読み方する特定の層にフォーカスしすぎてて逆に大変そう。example捨ててるし…

[honeybe]

今まさにOpenAPI定義を書いているし近い未来に必要になりそうではある。参考にする。

[berlysia]

yamlのままでも読みやすいOpenAPI(Swagger)の書き方をしている話。最終的にはツールを通して閲覧するが、レビューや変更内容の確認がしやすくなる