先月から、今年の秋くらいにリリース予定の新サービスの設計、開発を始めました。新しく始めるサービスなので、まだ経験したことがない言語やフレームワーク、技術を使わないと楽しくありません。Vue.jsも今回が初めて、というメンバーもおり、さらにRESTではなくgRPCも、となると未経験技術が多すぎてキャッチアップが追いつかなさそうということもあって見送りました。Vue.js(Typescript)を使うことになりました*1。gRPCは見送ったので、RESTのAPI定義一元化、コード自動生成を実現するためOpenAPIを利用することにしました。パシフィコ横浜は、横浜市にある世界最大級の国際会議場と展示ホールとホテルからなるコンベンション・センター。本文には特に関係ありません。APIのためのAPI定義フォーマットです。元々はSwaggerからスタートしたものですが、2016年から分離してOpenAPIとなりました。2017年7月に3.0がリリースされています。swagger.ioAPI定義の記述API定義はYAMLかJSONで書けます。定義が深くなるとYAMLよりJSONの方が書きやすいですが、JSONだとコメントが書けないので、どちらも一長一短です。今回はYAMLの例を示します。定義の作成には、Swaggerが提供しているEditorが便利です。dockerで起動するものもありますし、オンラインでも試せます。EditorOpenAPIの詳細仕様は以下を参考に。swagger.iopathsAPIのendpointと、必要なパラメータ、レスポンスを定義します。以下は、GETでリストを返す例です。"#/components/schemas/ApiTodos"queryパラメータだけでなく、pathパラメータも指定できます。"#/components/schemas/ApiTodo"もちろんPOSTなどGET以外のAPIも定義できます。定義を書いていく上で以下2点が分かりにくかったので補足しておきます。APIをグループ化するために指定します。上記の例では全てtodosグループにまとめられます。されてしまうので、何かは指定した方がいいです。APIによる操作(operation)を識別するためのIDです。大文字小文字は区別されます。後に生成するコードでこのIDがそのままメソッド名として使われるので、それを意識した命名にするとよいです。componentsAPI定義で繰り返し出現するような再利用可能なobjectを定義します。参照しているものです。先頭につけています*2。stringこれだけでAPI定義は完成です。Generatorで行います。openapi-generator対応している言語の一覧はここにあります。同じ言語でもフレームワークごとに別のGeneratorが用意されている言語もあります。使うコードを生成してみます。以下のように生成されました(後で説明する方法でフォーマットしてあります)。string;}APIクライアントも同じく生成されます。}}生成されたコード自体はimportするだけでよいので、元のコードを触ることなく利用できます。kotlin-springSpringBoot向けのKotlinのコードを生成してみます。