APIとしてサーバーサイドを開発する際、APIの定義書が必要になるかと思います。 （え、必要ないって？いやいや、まさかそんなはずは…）
知らなかったんですが、API周りは定義書とコードをセットで作れるOpenAPIというフレームワークがあるそうで、今回はそのメモです。
OpenAPI is 何？
まず、よくある注意書きで、OpenAPIとオープンAPIは違います。
オープンAPI
APIとはアプリケーション・プログラミング・インターフェースの略で、あるアプリケーションの機能や管理するデータ等を他のアプリケーションから呼び出して利用するための接続仕様・仕組みを指します。それを他の企業等に公開することを「オープンAPI」と呼びます。 オープンAPIって何？ | G.金融経済を学ぶ | 一般社団法人 全国銀行協会
同音異義語ですね。こっちは、「みんな使えるようにAPI用意するからねー」っていう取り組みみたいなもんです。
OpenAPI (Swagger)
今回対象にするのはこっち。上の方は個人的にはどうでもいい。
githubの導入部を訳すと、
OpenAPI仕様は、Linux Foundation Collaborative ProjectであるOpenAPI Initiative内のコミュニティ主導のオープン仕様です。
OpenAPI仕様（OAS）は、REST APIの標準のプログラミング言語に依存しないインターフェース記述を定義します。これにより、ソースコード、追加のドキュメント、またはネットワークトラフィックの検査を必要とせずに、人間とコンピューターの両方がサービスの機能を発見および理解できます。 OpenAPIを介して適切に定義されると、消費者は最小限の実装ロジックでリモートサービスを理解し、対話することができます。インターフェースの記述が低レベルのプログラミングのために行ったことと同様に、OpenAPI仕様はサービスを呼び出す際の推測を排除します。
(和訳：Google先生)
使ってみる
導入
Docker Imageが提供されているので、そちらを使用します。
めんどくさい方はswagger-editorなるサービスもあるので、そっちを使ってくださいな。
まずは、とりあえずイメージを引いてきます。
docker pull swaggerapi/swagger-editor
そんでもって起動します。
docker run -d -p 80:8080 swaggerapi/swagger-editor
あとは下記にアクセスすればこんな感じですね。
使い方
Swaggerにおいて、APIの定義にはyaml（もしくはjson）形式で記述します。 swagger editerで、左側に書いた内容で、APIの使用を示したものが右側に表示されています。
swaggerの構成としては、下記の記事を参考にすると、大体下記のようになっているようです。
APIの記述
実際にこの前の自由研究の内容で作成してみます。
画面としてはこんな感じですかね。
ファイル出力
①->②で形式を選択して、ドキュメントがダウンロードされます。
使用するときはREADMEを参照。
python-flask版をDockerを使用する場合には、
docker build -t swagger_server .
でビルドして、実行します。
docker run -p 8080:8080 swagger_server
ドキュメントを参照するときは
で確認できます。
今風の仕様書っぽくて非常に◎。
感想
一言でまとめると、
OpenAPI使いましょう。
以上。
