2018-02-22

OpenAPI 3の書き味

OpenAPI 3が実際どういう感じかはやっぱり書いてみないとわかりにくいだろうと思って、砂場として作っているRailsアプリのAPIのOpenAPIドキュメントを書いてみた。気づいたv2との大きめの違いは次のとおり。

  • componentsの配下に再利用できるパラメータやスキーマを書く
  • Operation ObjectのparametersからrequestBodyが分離された
  • Operation Objectのresponses配下にapplication/jsonのようなメディアタイプを明示するようになった

おもな機能だけ使っていると、それほどv2から離れた書きかたになるわけではなさそうなので、移行が厳しいということにはならないだろうし、元のドキュメントの状態によるかもしれないが機械的に変換することもできるだろうという感触だった。今回の試し書きでは使わなかったが、Schema Objectでnullbleが使えるようになったのは、スキーマ駆動開発勢としてはうれしいところなので、はやく移行したい。しかし、それには使っている周辺ツール/ライブラリ(おもにCommittee)に貢献していく必要がある…

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です