ApidogのIDEAプラグイン(Apidog Fast Request)やいくつかのSwaggerプラグインを使えば、コードからAPIドキュメントを簡単に生成でき、ゼロからドキュメントを作成する手間を省けます。
しかし、エンドポイントが記述され、ドキュメントが生成された後でも、APIのデザインは十分か？ドキュメントは標準化されているか？さらに改善できる点はどこか？といった疑問を感じるかもしれません。
特にチームでの共同作業では、APIドキュメントはチームメンバーが一目で理解できるものであるべきです。命名の明確さと情報の完全性は、APIの使用体験に直接影響します。
Apidogは最近、この段階でAPIドキュメントをさらに最適化するのに役立ついくつかのAI機能をリリースしました。既存のエンドポイントの詳細を改善する場合でも、他の場所から既存のAPIドキュメントをインポートする場合でも、AIは実践的な提案を提供できます。
ApidogのAIは、既存ドキュメントをもとに不足・不整合・非標準を段階的にチェックし、「使えるAPIドキュメント」から「信頼できるAPIドキュメント」へ導きます。
以下では、ApidogでAIを使用してより標準化されたAPIドキュメントを作成する方法を順を追って説明します。始める前に、Apidogを最新バージョンに更新し、AI機能を有効にし、AIモデルを設定していることを確認してください。
既存のAPIドキュメント、そのままAIで使える？
非標準フォーマットや不完全な定義でも、AIはどう補完できるのか
APIドキュメントを他のソースからApidogに移行する必要がある場合があります。ドキュメントが標準形式であれば、Apidogは複数のインポート方法をネイティブでサポートしています。IDEAプラグインを介してコードからドキュメントを生成したり、OpenAPI/Swagger仕様をインポートしたり、Postmanなどの他のツールから移行したりできます。
しかし、場合によっては、ドキュメントがこれらの標準形式ではないこともあります。たとえば、チームが以前にMarkdownでエンドポイントを文書化したり、Wordでフィールドの説明を整理したり、チャットログやメールでエンドポイントの定義を見つけたりした場合などです。これらの非標準ソースから各フィールドをApidogに手動で入力するのは大変な作業です。
このような状況では、データ入力に役立つ「AIによるスキーマ変更」機能を使用できます。例えば、次のようなMarkdownコンテンツがあるとします。
| name | desc | type | required |
| ---------- | --------------------------------------------------------------------------- | --------- | -------- |
| usePaging | ページネーションを有効にするかどうか | boolean | true |
| offset | 開始位置（ページネーションが有効な場合に必須） | int | false |
| pageSize | ページあたりのアイテム数（ページネーションが有効な場合に必須） | int | false |
| minPrice | 最小価格（単位：セント） | int | false |
| maxPrice | 最大価格（単位：セント） | int | false |
| brand | ブランドコード | string | false |
| categoryId | 製品カテゴリID | int | false |
| sortRule | ソートルール：1 → 売上優先、2 → 価格昇順、3 → 価格降順 | enum(int) | false |
| keyword | 検索キーワード（製品名のあいまい一致） | string | false |パラメータをコピーしてAIに「このコンテンツをエンドポイントパラメータに変換し、型と必須フィールドを特定してください。」と尋ねるだけです。
AIはフィールド名、データ型、必須ステータス、説明を自動的に検出し、すべてをApidogの標準スキーマ形式に変換します。列挙型が含まれている場合、AIはそれらを適切な列挙型として整理します。
AIはAPIドキュメントのどこまで改善できるのか？
フィールド名、説明、サンプルデータを整えるプロセス
基本情報をインポートした後、次のステップは詳細を洗練することです。
フィールド名が不明な場合は、「AI命名」機能を使用してください。AIは、エンドポイントの仕様とAPI設計規範に従って、より正確な命名の提案を提供します。
AIを使用してフィールドの説明を自動補完し、より明確で完全な説明にすることもできます。
モックデータの生成もAIの強みです。多くの場合、フィールドが何を表すかは分かっていても、どのような例の値を使用すべきか確信が持てません。AIはフィールドの型と説明に基づいて、妥当な例データを自動的に生成します。
そのAPIドキュメント、何が足りていないのか？
必須項目・レスポンス・例の抜け漏れをAIで可視化
ドキュメントがほぼ完成しているように見えても、重要な情報が不足していないか疑問に思うかもしれません。この時点で、Apidogの「APIドキュメント完全性チェック」を使用して、何か見落としがないか確認してください。
AIは、既存のAPIドキュメントを複数の視点からスキャンし、不足している情報や不完全な情報を特定します。その後、各レビュー項目を採点した詳細なレポートを生成し、APIドキュメントがどこを改善する必要があるかを素早く把握できるようにします。
レポートは、何をすべきかを教えるだけでなく、その理由も説明します。例えば、成功時のレスポンス形式は文書化しているが、考えられるエラーシナリオが欠けていたり、基本的なフィールド説明はあるが、使用上の制約やフォーマット要件が不足しているといった場合です。
レポートで提供された提案に従って、APIドキュメントを改善することができます。
エンドポイント間の不整合、どうやって防ぐ？
命名規則・型定義・レスポンス構造の一貫性チェック
APIドキュメントは完全であるだけでなく、十分に標準化されている必要があります。単一のエンドポイント内では、命名は一貫したスタイルに従い、フィールドの型は明確かつ正確に定義され、レスポンス構造は論理的であるべきです。これらの詳細は、ドキュメントを読みやすく、保守しやすくする上で重要な役割を果たします。
Apidogの「エンドポイント適合性チェック」機能は、複数の観点からドキュメントを検査します。例えば、一部のフィールドが動詞で命名され、他が名詞で命名されている場合、AIはその矛盾を指摘し、統一された命名スタイルを推奨します。
また、フィールドの定義が一貫した標準に従っているか（例：混合ケーシングスタイルの回避、アンダースコアとキャメルケースの同時使用、一貫性のない省略形など）をチェックし、これらの問題を修正するための明確な提案を提供します。
AIはAPIドキュメントを「完成」させるのか？それとも育てるのか
明確で標準化されたAPIドキュメントを作成することは不可欠です。AIが生成するテストケースのような機能は、ドキュメントの品質に依存します。ドキュメントが完全で一貫していればいるほど、生成されるテストケースはより正確で有用なものになります。
すべてのAI機能を一度に使用したり、現在のワークフローを抜本的に変更したりする必要はありません。
これは段階的なプロセスです。既存のドキュメントをインポートすることから始め、その後ゆっくりとAI機能を適用して改善および洗練していくことができます。提案について確信が持てない場合は、変更せずにそのままにしておき、より多くのコンテキストが得られたときに後で再検討することも可能です。
時間をかけて、APIドキュメントの標準に対する理解が自然と深まるでしょう。AIは目先の問題を解決するだけでなく、より良いドキュメント作成の習慣を身につけるのにも役立ちます。
