API Document Publication

wiki, tech, tech
Page content

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

todo

調査観点

  • 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
    • 本物そっくりの認証？

2018/09/20 頃の調査

  • ユーザ視点のドキュメント提供のレベル

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

  • テンプレ

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

swagger-codegen で静的html

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

asciidoctor

  • 公式サイト
  • 特徴・感想
  • 使い方
    • 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
  • ライセンス

swagger-ui

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

spectacle-docs

  • 公式サイト: 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
  • ライセンス
    • MIT (大丈夫だね)

readme.io

  • 公式サイト
  • 特徴・感想
    • hosted 動的 html
    • oauth2.0付きの try! ボタンが作れていい。
    • コードサンプルもある
    • box の api reference とか
    • お金はちゃんとかかりますね
  • 使い方
  • ライセンス

postman documentation

  • 公式サイト
  • 特徴・感想
    • sample req/res を好きなように載せられるのが良いところ

      • example は他にも書き方を発見したので唯一の強みではなくなった。むしろ Open API Spec の枠組みから逸脱するので再利用性の点で✕

    • mock も連動して動く (ただし、 path や query param で区別がつかないほど細かい req は res 分けられない)
  • 使い方
    • swagger 連携できる？？
  • ライセンス

Stoplight (2019/01/02)

  • official: https://stoplight.io/

  • SendGrid API v3 reference を眺めていて発見した。かっこいい。使えるかどうかは要確認。 OpenAPI 対応でテスト機能があると書いているので swagger spec も使いまわせそう。

  • 公式サイト

  • 特徴・感想

  • 使い方

  • ライセンス

redoc (2020/05/30)

  • 公式サイト
  • 特徴・感想
    • ええ感じ、使えそう
  • 使い方
    • https://dev.classmethod.jp/articles/openapi-firebase-hosting/
    • 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
  • ライセンス
    • Apache 2.0 (ゆるーい)