2017/5/26 ドキュメントを見たらもっとかんたんにできることに気づきアップデートしました。
APIドキュメントの標準フォーマットとして注目されているSwagger。
（参考：RESTful APIの記述標準化を担うSwaggerとは？ | NTT Communications Developer Portal）
色々とできるのはいいんですが、セットアップしたくても
どれから手を付けていいのかわかりづらいので
Macでのセットアップ方法を残します。
前提条件
- MacOS向けです。Windows向けでも適宜読み替えれば使えるとは思います。
- 操作を統一するためターミナルを使う例でご紹介します。
ドキュメントを書く
ドキュメントを書く場合は
オンラインでSwaggerEditorにアクセスして書けるので
いますぐに書きたいひとはそちらを利用すると良いかと思います。
ただネット環境がないと使えなくなってしまうので
オフラインでもかけるようにSwaggerEditorをローカル使うための説明を
以下に記載しておきます。
※ただ読みたいだけの人はこの項目は読み飛ばしてもらってかまいません。
SwaggerEditorをダウンロードする
githubのリポジトリからソースを落としてくるだけです。
# curlでダウンロード
$ curl -L -O https://github.com/swagger-api/swagger-editor/archive/v3.0.10.zip
# 解凍
$ unzip v3.0.0.zip
今回は v3.0.10 を使う想定にしています。
適宜最新版を落としたい場合はGithubのリリースで
バージョン番号を調べて適宜差し替えてください
SwaggerEditorを起動する
解凍したディレクトリの直下にある index.html をブラウザで開けば使えます。
# 該当のindex.htmlをブラウザで開く、今回はopenコマンド開く
$ open ./swagger-editor-3.0.10/index.html
ドキュメントを編集、出力する
yamlの書き方が特殊なので日本語情報は以下のものを参照
編集が終わったら「File」→「Download JSON」でjsonがダウンロードできるので
こちらを手元で保存します。
もし再編集したい場合は「Import File...」からJSONを読み込むことができるので
そこから手直しをします。
ドキュメントを読む
SwaggerEditorで編集したJSONデータは
SwaggerUIで読みこんで閲覧することができます。
SwaggerUIをダウンロードする
SwaggerEditorとはリポジトリが別ななので
こちらもgithubのリポジトリからソースを落としてきて
開くだけです。
$ curl -L -O https://github.com/swagger-api/swagger-ui/archive/v3.0.12.zip
$ unzip v3.0.12.zip
こちらは v3.0.12 を使う場合です。
Editor同様に適宜最新版を落としたい場合はGithubのリリースで
バージョン番号を調べて適宜差し替えてください
jsonを読み込んで表示する
SwaggerUiは解凍したディレクトリの
dist/index.htmlを開けば使えるので
ブラウザで開いて表示します。
$ open swagger-ui-3.0.12/dist/index.html
上のスクリーンショットのように
ページ上のテキストボックスに見たいjsonのアドレスを入力して
Explore を押せば表示されます
Tips:ローカルのjsonファイルを表示したい場合
上記の例はインターネット上のjsonファイルを開く場合の例ですが
ローカルに保持しているjsonを開きたいケースもあると思います。
SwaggerUIがローカルのファイルパスには対応していないのと
Cross-originの関係でエラーになるため
ローカルでサーバを立ててあげるなどしたほうがスムーズです。
色々手法はあるので方法はありますが
Macの場合はPHPがデフォルトで入っているので
PHPのビルトインウェブサーバーを使う方法をご紹介します。
# swagger-uiのdist配下にみたいファイルを配置します
# 今回は ~/swagger.json というファイルを例に示します
$ cp ~/swagger.json swagger-ui-3.0.12/dist/swagger.json
# ビルドインウェブサーバの起動
$ php -S localhost:8082 -t swagger-ui-3.0.12/dist/
※8082にしたのは他のものとの被り回避
これでページ上の欄にhttp://localhost:8082/を開くと
SwaggerUIが見れるようになりテキストボックスに
http://localhost:8082/swagger.json と
入れてあげれば見れるようになります。