goa tips: swagger-ui がサービスできないときのドキュメントどうする問題

概要

goa は swagger ドキュメントを生成してくれるので,これを swagger-ui をつかってサービスしてやると API が分かりやすく,お試しも出来てかなりいいかんじになります.しかし,環境によってはサービスを立ち上げることが出来ないとか,ドキュメントを確認して欲しい人がサービスにアクセスできないとかいうことが結構あります.そんなとき swagger.(json|yaml) をそのまま渡して 「swagger editor でみてね!」が通じない場合の対処方法です.

ブラウザで見れるように加工する

bootprint を使う

swagger.json を変換してブラウザで見れるように変換したものを用意します.利用するのは bootprint と bootprint-swagger です. これは npm で最初に一回インストールしておけばいいです.

Makefile に入れておいて,毎回生成しておくと吉だと思います.

準備

npm i -g bootprint
npm i -g bootprint-swagger

実行

$ bootprint swagger swagger/swagger.json api-doc

swagger-codegen-cli を使う

参考:https://github.com/swagger-api/swagger-codegen/blob/master/README.md#generating-static-html-api-documentation

準備

wget http://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar -O swagger-codegen-cli.jar

nodeでサービスできる状態にする

以下でコードを生成した後,同じディレクトリで npm -installnode . でサービス立ち上げられます.localhost:8002にアクセスすると見た目キレイなドキュメント見られる.でも,結局手元で node 立ち上げてもらって閲覧してもらわないといけないので,ちょっと敷居高い.

実行

$ java -jar swagger-codegen-cli.jar generate -i swagger.json -l dynamic-html
$ npm install
$ node .

f:id:ikawaha:20161024154332p:plain

static な html として出力

こっちはホントに静的なhtmlドキュメント.

実行

$ java -jar swagger-codegen-cli.jar generate -i swagger.json -l  html

asciidoc / markdown に変換する

なにかこう,wiki的なものに markdown で残しておきたいときは swagger2markup を使うといいです.

http://swagger2markup.github.io/swagger2markup/1.0.1/#_command_line_interface

CLI用のツールがあるのでダウンロード

使い方

fooディレクトリを作ってそこに変換したドキュメントを生成します. 実行時のプロパティとして config.properties に書かれた値を利用します.

$ java -jar ~/lib/java/swagger2markup-cli-1.0.1.jar convert -i ./swagger/swagger.json -d ./foo -c ./config.properties

プロパティ

上で config.properties に書かれたプロパティを利用すると書きましたが,ファイル名は任意です. 指定できる値は下記にまとまっています.

http://swagger2markup.github.io/swagger2markup/1.0.1/#_swagger2markup_properties

とりあえず,markdown か asciidoc かだけを設定しておけばいけそう.デフォルトは asciidoc. なので,markdown にしたければこれで指定して下さい.

例:

swagger2markup.markupLanguage=MARKDOWN

とりあえず,こんな方法がありますが,もっといい方法があれば教えて欲しいです ╭( ・ㅂ・)و ̑̑