API Document Publication

May 29, 2020 (Last Modified: September 20, 2020)

Page content

API Doc の公開方法調査するぞー

openapi spec statis html generator とかで検索
redoc-cli が良さそうとの声 https://dev.classmethod.jp/articles/openapi-firebase-hosting/
swagger-codegen とかもあるかな
license も気をつけて選択しなきゃねぇ

must
- Open API Spec file で完結できること
- ある程度の可読性
- なるべく sample req/res を充実させ, FAQ を潰す
should
- 仕様と動作を整合させたい -> try ボタンと mock など
- webページのセキュリティは用途による
- 記述しておきたいコンテンツ
  - SSL証明書, TLSv1.2, 認証方式
  - システム間連携のためなら: client/server とその数, 接続はIPかFQDNか, retry仕様
may
- 実装サンプルコードも出ると嬉しい
- public に見せたくない endpoint は別表示 -> だいたい運用の問題なのでツール関係ない
etc
- 本物そっくりの認証？

ユーザ視点のドキュメント提供のレベル
1. apispec.yaml ファイルを提供するだけ、閲覧方法はユーザ任せ -> 玄人向け
2. 静的 html ファイルの提供 -> これもまだ不自由、ファイルの受け取りがお互いに面倒
3. 動的webページ の提供 -> リッチで、お金で実現する場合が多い

テンプレ

- 公式サイト
- 特徴・感想
- 使い方
- ライセンス

申し訳程度に用意しました感がすごく、あまりにもチープで可読性も低く、無いわぁ、という感じ。

公式サイト
特徴・感想
- 静的htmlの候補。だが乏しいなぁ‥
- なにより作成ステップが面倒でない感じ
- 参考: Swagger 定義ファイルからそこそこいい感じの静的 REST API ドキュメント作成する
使い方
- swagger.yaml の用意
- gradle (javaのbuilder?) をインストール: brew install gradle
- swagger2markup のインストール: git clone https://github.com/Swagger2Markup/swagger2markup-cli.git
- swagger2markup の実行 (swagger -> Asciidoc の変換): java -jar swagger2markup-cli-1.1.0.jar convert -i swagger.yaml -f api-doc
  - 実行すると api-doc.adoc が出力されます。
- asciidoctor のインストール: brew install asciidoctor
- asciidoctor の実行 (asciidoc -> html 変換): asciidoctor -a toc=left api-doc.adoc
  - エラーでまくるけど, markdownとかの見出しレベルのズレで怒られているだけなので今は無視
```
asciidoctor: ERROR: api-doc.adoc: line 6: level 0 sections can only be used when doctype is book
asciidoctor: WARNING: api-doc.adoc: line 33: section title out of sequence: expected level 1, got level 2
```
ライセンス

公式サイト
特徴・感想
- 自前の動的 html
- 内部ではこれで十分
使い方
- 略
- 応用: gitlab に上がった swagger.yaml を「swagger-ui で見る」ボタンを押すと見られる！ gitlab にそんなプラグインを書くことができる。ラボ環境用の gitlab で使ってる
ライセンス

公式サイト: https://sourcey.com/spectacle, github, npmjs
特徴・感想
- 見た目は大変よろしい。カスタマイズで色々追加できればswagger ui を超えるか（コードサンプル出力）
- intercomとかサンプルの事例も紹介されているので、それを真似してコードサンプルも出るようにできれば、こっちがいいかな

使い方

node.js 8 以上で npm install spectacle-docs で動く

$ ./node_modules/.bin/spectacle -d ../api_spec_apigw/swagger2.yaml

公式サイト
特徴・感想
- sample req/res を好きなように載せられるのが良いところ
  - example は他にも書き方を発見したので唯一の強みではなくなった。むしろ Open API Spec の枠組みから逸脱するので再利用性の点で✕
- mock も連動して動く (ただし、 path や query param で区別がつかないほど細かい req は res 分けられない)
使い方
- swagger 連携できる？？
ライセンス

official: https://stoplight.io/
SendGrid API v3 reference を眺めていて発見した。かっこいい。使えるかどうかは要確認。 OpenAPI 対応でテスト機能があると書いているので swagger spec も使いまわせそう。
公式サイト
特徴・感想
使い方
ライセンス

使い方

redoc の docker 版でサーバーを立ち上げる場合

docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc

redoc-cli でサーバーを立ち上げる場合

npm install -g redoc-cli
redoc-cli serve https://api.example.com/openapi.json

redoc-cli で静的HTMLを出力する場合

npm install -g redoc-cli
redoc-cli bundle https://api.example.com/openapi.json