APIドキュメントをExcelやPDFで作成し、メールで共有するやり方はあまりにもおなじみです。
問題が発生すると担当者に連絡し、過去のメールを探して顧客企業が持っているドキュメントのバージョンを確認します。変更内容を改めて説明し、修正したドキュメントを送ったあと、正しく反映されたかをまた確認します。
私たちはこのプロセスをあまりにも多く繰り返してきたため、本来必要な業務だと思うようになってしまいました。
しかし問題は、1つの誤ったドキュメントだけでは終わりません。
APIが変更されるたびに、新しいファイルとメール、顧客企業ごとの例外、担当者の記憶が一つずつ積み上がっていきます。最初は小さな不便でも、時間が経つほどどのドキュメントが基準なのか確認しづらくなり、問題解決に必要な人と時間も増えていきます。
顧客企業が以前のバージョンのリクエスト形式で開発すると、連携エラーや手戻りが発生します。必須項目や認証方式が異なって伝わると開発スケジュールが遅れ、すでに運用中のAPIであればデータエラーや障害につながることもあります。
問題が起きて初めて、社内の開発チームと顧客企業が別々のドキュメントを見ていたことに気づきます。
そこから開発者は進めていた作業を止め、原因を確認します。運用担当者は過去のドキュメントと伝達履歴を探し、顧客企業は自分たちの実装と受け取った仕様を再検証します。1つのドキュメント不一致が、複数の人の仕事を同時に止めてしまいます。
それでも多くの問題は、電話やメール、メッセンジャーで静かに解決されます。
誰かが修正済みのファイルを再送し、誰かが顧客企業に状況を説明し、開発者は急いで例外処理を追加します。目の前の問題は解決しますが、なぜ発生したのか、どの顧客企業が影響を受けたのか、同じ問題を繰り返さないために何を変えたのかは、組織には残りません。
このプロセスに使われる時間は、本来は開発やプロダクト改善に使われるべき時間です。
さらに大きな問題は、このすべてのプロセスが特定の担当者の経験や記憶、メールボックスに依存していることです。担当者が席を外したり退職したりすると、組織はメールやメッセンジャーの履歴を掘り起こし、業務を再び復元しなければなりません。
管理されていないAPIドキュメントは消えません。組織の内外に残り続け、見えないドキュメント負債になります。
私たちは問題を解決しているのではなく、問題が発生するたびに人の時間で食い止めるやり方に慣れてしまっただけなのかもしれません。
こうした問題を実際の業務で経験した私は、スペックブリッジを作りました。
スペックブリッジは、単にAPIドキュメントを作成するツールではありません。ドキュメントの変更内容をレビューし、承認されたバージョンだけを顧客企業や外部パートナーに配布する、APIドキュメント運用ツールです。
既存のSwaggerを置き換えるのではなく、Swagger/OpenAPIとPostman Collectionを取り込んだうえで、外部への共有プロセスで発生する問題を管理することに注力しました。
- 現在の配布版と修正版の差分比較
- 変更内容のレビューと承認
- 下書きと顧客企業が見る配布版の分離
- 顧客企業ごとのドキュメント公開範囲の管理
- 公開リンクのパスワードと有効期限の設定
- 同じリンクで承認済みの最新ドキュメントを提供
顧客企業に毎回新しいファイルを送る必要はなく、社内レビューが完了したドキュメントだけを既存のリンクに再配布できます。
開発者はドキュメントを探して再送する反復作業を減らせますし、組織は特定の担当者の記憶ではなく、記録された変更履歴と配布基準に基づいてAPIドキュメントを管理できます。
現在、スペックブリッジを実際のAPIドキュメント運用に使い、率直なフィードバックをくださるパートナーを探しています。
ExcelやPDFでAPIドキュメントを管理していたり、APIが変更されるたびに顧客企業へドキュメントを再送しているチームであれば、現在使っているドキュメント1つから一緒に検証してみたいです。
よくできた機能への称賛よりも、実際の運用で不便な点、不要な手順、足りない機能について率直な意見を聞きたいです。
まだコメントはありません。