adding-api-docs

API ドキュメントを追加する（OpenAPI）

ユーザーから API ドキュメント、Swagger、OpenAPI 仕様、またはエンドポイントドキュメントの生成を求められた場合に、このスキルを使用します。

手順

1. API フレームワークを特定する — Express、Fastify、Next.js API routes、Hono、Django REST Framework、FastAPI などが使われているか確認します。

2. Node.js／Express の場合 — swagger-jsdoc と swagger-ui-express をインストールします。

   npm install swagger-jsdoc swagger-ui-express
   npm install -D @types/swagger-jsdoc @types/swagger-ui-express
   

   ルートハンドラーの JSDoc アノテーションから OpenAPI 仕様を作成します。

   /**
    * @openapi
    * /api/users:
    *   get:
    *     summary: List all users
    *     responses:
    *       200:
    *         description: A list of users
    */
   

3. Next.js API routes の場合 — openapi.json ファイルを手動で作成するか、next-swagger-doc を使ってルートハンドラーから生成します。仕様を /api/docs で配信します。

4. FastAPI（Python）の場合 — ドキュメントは /docs（Swagger UI）と /redoc に組み込まれています。スキーマが自動生成されるよう、リクエスト／レスポンスの型には Pydantic モデルを使用します。

5. インタラクティブなドキュメント UI を追加する — Swagger UI を /docs ルートで配信するか、最新の代替手段として Scalar／Redoc を使用します。

   npm install @scalar/express-api-reference
   

6. スキーマを定義する — リクエスト本文とレスポンス用の Zod スキーマ（または JSON Schema）を作成し、OpenAPI 仕様から参照します。TypeScript プロジェクトでは、zod-to-openapi を使用して既存の Zod バリデーターからスキーマを生成します。

7. 認証に関するドキュメントを追加する — OpenAPI の securitySchemes セクションに、認証方式（Bearer トークン、API キー、OAuth2）を記載します。

補足

• 仕様を実際の API と同期させます。別個の YAML ファイルを管理するより、可能であればコードから生成します。
• 開発者の利便性を高めるため、スキーマに値の例を追加します。
• コードとともに API ドキュメントをバージョン管理します。