Designing APIs with Swagger and OpenAPI
目次
はじめに
REST APIは、ソフトウェアのAPIの基本だと思いますが、
そのドキュメントの書き方は結構悩ましいと思います。
仕様変更すると、すぐにドキュメントとソースコードの乖離が発生しますし、
ソースコードとドキュメントを同じgit リポジトリで管理しようと思っても、
仕様書としてよく使われるWordやExcelはバイナリファイルなので、
バージョン管理がしずらいです。
そこで、テキストファイルであるyamlやjsonファイルを使って
REST APIの仕様を記述する標準があります。
それが、OpenAPIです。
以前はSwaggerというOSSのプロジェクトが使っていた仕様なので、
Swaggerと呼ばれることもあります。
本記事では、このOpen APIによるREST APIの仕様書作成の
特徴と仕様書作成方法などをまとめておきたいと思います。
Open APIの特徴
下記がOpen APIの特徴です。
1. YAMLやJSONなどのテキストファイルで仕様を記述できる。
ですので、gitなどのバージョン管理システムとの親和性が高いです。
また、使うプログラミング言語に関係なく、仕様を記述できます。
テキストファイルなので、普通のエディタでも編集できますが、
SwaggerEditorというWebツールを使うと、仕様のプレビューも見れて便利です。
また、この仕様ファイルはAPIサーバのリポジトリに
単一ファイルで置かれることが多いようです。
2. OpenAPIの仕様データから、仕様書を自動生成できる。
OpenAPIの仕様データがあれば、
そのデータから簡単にAPIドキュメントを作成することもできます。
公式のSwagger UIも使えますし、
後述のRedoclyのツールを使うと、
シングルHTMLファイルで仕様書を生成することもできます。
3. OpenAPIの仕様データから、APIのクライアントやサーバのコードを自動生成できる
仕様の定義だけでなく、様々なプログラミング言語用に、
定義ファイルから自動で、クライアントやサーバーのコードを自動生成できるツールも公開されています。
Open APIの仕様の書き方
こちらの公式の仕様書を見るとわかりやすいと思います。
シングルHTMLファイルのAPIドキュメントを生成する
OpenAPIのツールを使うと、
Webサービスベースのドキュメントを作成できますが、
本当にREST APIのドキュメントとして利用する場合は、
HTMLファイルのシングルファイルとして、ドキュメントファイルを出力し、
ブラウザーでいつでもみれると便利です。
これを実現するには、下記のRedoclyのツールを使うと便利です。
サンプルとして、こちらの定義ファイルを使ってみます。
こちらのファイルをDLし、そのファイルのディレクトリにターミナルで移動したあと、
こちらのコマンドでdocker imageをpullします。
$ $ docker pull redocly/openapi-cli
あとは、下記のコマンドを入力すれば、index.htmlというファイルで出力されます。
$ docker run -it -v "$(pwd)/:/data" broothie/redoc-cli bundle /data/api-with-examples.json -o index.html
上記のコマンドのapi_with_examples.jsonの部分の名前を変更すれば、様々なファイルを出力できます。
参考資料
Designing APIs with Swagger and OpenAPI
MyEnigma Supporters
もしこの記事が参考になり、
ブログをサポートしたいと思われた方は、
こちらからよろしくお願いします。
