api ドキュメント保守の考察

今晩から東京出張なので運動はおやすみ。縄跳びだけもっていく。

api ドキュメントを継続的に保守することへの考察⌗

お手伝い先のプロダクトを1年半以上、継続している。web api の機能もどんどん増えてきて50は超えていると思う。api ドキュメントをビルドするために redocly cli というツールを使っている。次のスクリプトは .gitlab-ci.yml の設定だけど、このぐらいの手間で openapi.yml から1つの html ドキュメントを生成してくれる。この index.html を api サーバーに同梱している。

  before_script:
    - node --version
    - npm --version
    - npm install @redocly/cli@latest
    - npx redocly --version
  script:
    - |+
      npx redocly build-docs schema/openapi.yml \
        --output index.html \
        --theme.openapi.schemaExpansionLevel=10 \
        --theme.openapi.expandResponses=all \
        --theme.openapi.requiredPropsFirst=true \
        --theme.openapi.jsonSampleExpandLevel=10 \
        --theme.openapi.hideLoading=true \
        --theme.openapi.pathInMiddlePanel=true      
    - mkdir -p public
    - mv index.html public/

web api の機能数が少ないときはこれで十分だった。しかし、50を超えてくると yml で api ドキュメントを保守するのが辛くなってくる。xml/yml/json を問わず、サイズの大きいこれらのファイルを保守するのはつらい。人間の能は複数種別の情報を同時処理できるが、一定量を超えた情報量をうまく処理できない。もちろん機能別にファイル分割して管理しているのだけど、それでも openapi.yml のエンドポイントの定義はどんどん増えていく。それがだんだん辛くなってきたのが現状になる。

以前 静的サイトジェネレーター勉強会の手伝い をしたときに slate という markdown で記述できる api ドキュメントツールがあることを教えてもらった。これはいいなとそのとき思ったのだけど、コミット履歴などをみているともう保守モードで活発に開発されていない。oss あるある話しで継続的に開発されていないツールはすぐに廃れるのでいまから採用するには躊躇してしまう。

postman という api プラットフォームがある。昔から api クライアントとして使う開発者も多かったのでツール自体は知っていた。この機会に私も実際に使ってみて評価した。既存の openapi.yml + redocly cli を使っているドキュメント管理と postman との比較をした。

• postman はドキュメントのバージョン管理ができる
• postman アプリを api ドキュメントのエディターとして使える
  • テキストの説明欄に markdown を記述できる
  • エクスポートすると json データになる
    • ドキュメントのデータとして yml と大きな違いはないが、エディターで隠蔽されるからドキュメントの保守はやりやすくなる
      • 但し、エディターは postman アプリに依存する
• postman はリクエスト CLI とレスポンスの対応関係をセットで管理できる
• ドキュメントの構造や見た目はあまり変わらない

postman そのものは悪くないけど、うちらのいまの開発のワークフローにすぐに適用できる状況でもない。postman の機能を有効に活用できるように開発のやり方を変えないといけない。そうしないと、ドキュメント管理だけに使うには外部サービス依存が大きくて学習コストも高くなってしまう。

別のアプローチとして openapi.yml の編集をテキストファイルで行うのではなく、人間にとって操作しやすいエディター上で行えるようにしたものが stoplight studio になる。ググると評判もよいし、私も実際に使ってみて機能はまさに探していたツールではある。しかし、このツールの先行きも怪しい。これまでデスクトップ版のエディターは無償で提供されていて、いまもアカウント登録すれば無償で使える。しかし、昨年あたりに SmartBear 社 (swagger を作ってた会社ね) に買収されている。おそらく swagger editor の移行先を探していてちょうど都合がよいのだと思う。SmartBear 社は過去の openapi 移行時のゴダゴダがあって印象がよくないし、ビジネス寄りの会社になるので将来的に stoplight studio を無償で使い続けられるかどうかにも懸念がある。

• SmartBear to Acquire Stoplight to Deliver Industry’s Broadest Portfolio of API Development Capabilities

今回は調査したどのツールにも懸念があって採用を見送ることにした。api ドキュメントを書くツールを探すのは難しい。

寝台特急⌗

久しぶりの寝台特急。11時25分頃に乗車券を使って JR 三ノ宮駅の改札を通過しようとするとエラーになった。30日から有効とは書いてあるものの、以前は通過できていた気がしたので駅員さんに聞いたら30分前から通れるはずとの。その後11時38分には改札を通れた。これまで改札でエラーになったことがなかったのは11時30分をまわってからだったんだと初めて気付いた。運が悪いことに0時11分発の予定が32分遅延した。調子の悪いときはこんなもので段取りもうまくいかない。最終的に東京駅には15分ほど遅れになった。

今日は普通のB寝台シングルを予約した。下側の狭い部屋でゆっくり寝ることにした。乗車後10分ほどして車掌さんが切符確認にきた。これもわかっているから扉を開けて切符も用意して待ってた。寝台特急は薄い布団しかついていないから冬はちょっと寒い。逆に夏はエアコンが効いているし薄い布団で問題ない。寝台特急は暖かい時期に乗るのがよさそうだということもわかってきた。