api-documentation

API ドキュメントのワークフロー

概要

OpenAPI／Swagger 仕様、開発者向けガイド、コード例、インタラクティブなドキュメントなど、包括的な API ドキュメントを作成するための専門的なワークフローです。

このワークフローを使用する場面

次のような場合に、このワークフローを使用します。

• API ドキュメントを作成する
• OpenAPI 仕様を生成する
• 開発者向けガイドを作成する
• コード例を追加する
• API ポータルをセットアップする

対象範囲と実行

ユーザーのタスクに合ったフェーズを選択してください。このドキュメントは目次であり、一覧にあるすべてのスキルを実行する指示ではありません。選択したスキルを使用する前に、その内容を確認してください。リポジトリとユーザーの制約を守ってください。クラウドへの呼び出し、ホスト設定、公開、破壊的な操作、支出には、該当する許可が必要です。ワークフローのチェックリスト自体は、実行の許可を与えるものではありません。

実際の実装／仕様を契約の基準とし、例にシークレットを含めないでください。「試す」機能では実際のリクエストが送信されることがあります。明示的に指定されたサンドボックスエンドポイントとテスト用認証情報を使用してください。公開前にドキュメントをローカルでプレビューしてください。デプロイは別途許可が必要な操作です。

ワークフローのフェーズ

フェーズ 1：API の調査

使用するスキル

• api-documenter - API ドキュメント
• api-design-principles - API 設計

作業

1. エンドポイントを一覧化する
2. リクエスト／レスポンスを文書化する
3. 認証方式を特定する
4. エラーコードを整理する
5. レート制限を記録する

コピーして使えるプロンプト

Use @api-documenter to discover and document API endpoints

フェーズ 2：OpenAPI 仕様

使用するスキル

• openapi-spec-generation - OpenAPI
• api-documenter - API 仕様

作業

1. OpenAPI スキーマを作成する
2. パスを定義する
3. スキーマを追加する
4. セキュリティを設定する
5. 例を追加する

コピーして使えるプロンプト

Use @openapi-spec-generation to create OpenAPI specification

フェーズ 3：開発者向けガイド

使用するスキル

• api-documentation-generator - ドキュメント
• documentation-templates - テンプレート

作業

1. はじめにのページを作成する
2. 認証ガイドを作成する
3. 一般的なパターンを文書化する
4. トラブルシューティングを追加する
5. FAQ を作成する

コピーして使えるプロンプト

Use @api-documentation-generator to create developer guide

フェーズ 4：コード例

使用するスキル

• api-documenter - コード例
• tutorial-engineer - チュートリアル

作業

1. リクエスト例を作成する
2. SDK の使用例を作成する
3. curl の使用例を追加する
4. チュートリアルを作成する
5. 例をテストする

コピーして使えるプロンプト

Use @api-documenter to generate code examples

フェーズ 5：インタラクティブなドキュメント

使用するスキル

• api-documenter - インタラクティブなドキュメント

作業

1. Swagger UI をセットアップする
2. Redoc を設定する
3. 試す機能を追加する
4. インタラクティブ機能をテストする
5. ドキュメントをデプロイする

コピーして使えるプロンプト

Use @api-documenter to set up interactive documentation

フェーズ 6：ドキュメントサイト

使用するスキル

• docs-architect - ドキュメントのアーキテクチャ
• wiki-page-writer - ドキュメント

作業

1. プラットフォームを選択する
2. 構成を設計する
3. ページを作成する
4. ナビゲーションを追加する
5. 検索を設定する

コピーして使えるプロンプト

Use @docs-architect to design API documentation site

フェーズ 7：保守

使用するスキル

• api-documenter - ドキュメントの保守

作業

1. 自動生成をセットアップする
2. 検証を設定する
3. レビュープロセスを追加する
4. 更新をスケジュールする
5. フィードバックを監視する

コピーして使えるプロンプト

Use @api-documenter to set up automated doc generation

品質ゲート

• OpenAPI 仕様が完成している
• 開発者向けガイドが作成されている
• コード例が動作する
• インタラクティブなドキュメントが機能する
• ドキュメントがデプロイされている

関連するワークフローバンドル

• documentation - ドキュメント
• api-design-principles - API 契約の設計
• development - 開発

制限事項

• タスクが上記の対象範囲に明確に合致する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。