Swaggerでいますぐドキュメントを書きたい/読みたい人のためのセットアップガイド

  • 26
    Like
  • 2
    Comment

2017/5/26 ドキュメントを見たらもっとかんたんにできることに気づきアップデートしました。

APIドキュメントの標準フォーマットとして注目されているSwagger。
(参考:RESTful APIの記述標準化を担うSwaggerとは? | NTT Communications Developer Portal
色々とできるのはいいんですが、セットアップしたくても
どれから手を付けていいのかわかりづらいので
Macでのセットアップ方法を残します。

前提条件

  • MacOS向けです。Windows向けでも適宜読み替えれば使えるとは思います。
  • 操作を統一するためターミナルを使う例でご紹介します。

ドキュメントを書く

ドキュメントを書く場合は
オンラインでSwaggerEditorにアクセスして書けるので
いますぐに書きたいひとはそちらを利用すると良いかと思います。

ただネット環境がないと使えなくなってしまうので
オフラインでもかけるようにSwaggerEditorをローカル使うための説明を
以下に記載しておきます。
※ただ読みたいだけの人はこの項目は読み飛ばしてもらってかまいません。

SwaggerEditorをダウンロードする

githubのリポジトリからソースを落としてくるだけです。

swagger-editorのダウンロード
# 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 をブラウザで開けば使えます。

swagger-editorを開く
# 該当の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を開けば使えるので
ブラウザで開いて表示します。

index.htmlを開く
$ open swagger-ui-3.0.12/dist/index.html

スクリーンショット 2017-05-27 19.39.28.png

上のスクリーンショットのように
ページ上のテキストボックスに見たいjsonのアドレスを入力して
Explore を押せば表示されます

Tips:ローカルのjsonファイルを表示したい場合

上記の例はインターネット上のjsonファイルを開く場合の例ですが
ローカルに保持しているjsonを開きたいケースもあると思います。

SwaggerUIがローカルのファイルパスには対応していないのと
Cross-originの関係でエラーになるため
ローカルでサーバを立ててあげるなどしたほうがスムーズです。

色々手法はあるので方法はありますが
Macの場合はPHPがデフォルトで入っているので
PHPのビルトインウェブサーバーを使う方法をご紹介します。

ビルトインウェブサーバーを使う形で閲覧
# swager-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
入れてあげれば見れるようになります。