web api の機能数が少ないときはこれで十分だった。しかし、50を超えてくると yml で api ドキュメントを保守するのが辛くなってくる。xml/yml/json を問わず、サイズの大きいこれらのファイルを保守するのはつらい。人間の能は複数種別の情報を同時処理できるが、一定量を超えた情報量をうまく処理できない。もちろん機能別にファイル分割して管理しているのだけど、それでも openapi.yml のエンドポイントの定義はどんどん増えていく。それがだんだん辛くなってきたのが現状になる。
以前 静的サイトジェネレーター勉強会の手伝い をしたときに slate という markdown で記述できる api ドキュメントツールがあることを教えてもらった。これはいいなとそのとき思ったのだけど、コミット履歴などをみているともう保守モードで活発に開発されていない。oss あるある話しで継続的に開発されていないツールはすぐに廃れるのでいまから採用するには躊躇してしまう。
postman という api プラットフォームがある。昔から api クライアントとして使う開発者も多かったのでツール自体は知っていた。この機会に私も実際に使ってみて評価した。既存の openapi.yml + redocly cli を使っているドキュメント管理と postman との比較をした。
久しぶりの寝台特急。11時25分頃に乗車券を使って JR 三ノ宮駅の改札を通過しようとするとエラーになった。30日から有効とは書いてあるものの、以前は通過できていた気がしたので駅員さんに聞いたら30分前から通れるはずとの。その後11時38分には改札を通れた。これまで改札でエラーになったことがなかったのは11時30分をまわってからだったんだと初めて気付いた。運が悪いことに0時11分発の予定が32分遅延した。調子の悪いときはこんなもので段取りもうまくいかない。最終的に東京駅には15分ほど遅れになった。