Anthropic Claudeソフトウェア開発⭐ リポ 0品質スコア 50/100

openapi-spec-generation

Name: openapi-spec-generation
Author: wshobson

コードやデザインファーストの仕様からOpenAPI 3.1仕様を生成・管理し、バリデーションパターンも適用します。APIドキュメントの作成、SDKの生成、またはAPIコントラクトの準拠確認が必要なときに使用してください。

description の原文を見る

Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.

SKILL.md 本文

OpenAPI 仕様生成

RESTful API の OpenAPI 3.1 仕様を作成、保守、検証するための包括的なパターン集です。

このスキルを使う場面

API ドキュメントをゼロから作成する
既存コードから OpenAPI 仕様を生成する
API コントラクトを設計する（デザインファースト手法）
仕様に対する API 実装を検証する
仕様からクライアント SDK を生成する
API ドキュメントポータルをセットアップする

コア概念

1. OpenAPI 3.1 構造

openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  securitySchemes: ...

2. デザインアプローチ

アプローチ	説明	最適な用途
デザインファースト	コード前に仕様を記述	新規 API、コントラクト定義
コードファースト	コードから仕様を生成	既存 API
ハイブリッド	コードにアノテーションを付与して仕様を生成	進化する API

テンプレート

テンプレート 1: 完全な API 仕様

openapi: 3.1.0
info:
  title: User Management API
  description: |
    ユーザーとそのプロフィールを管理する API です。

    ## 認証
    すべてのエンドポイントは Bearer トークン認証が必要です。

    ## レート制限
    - スタンダード層: 1 分あたり 1000 リクエスト
    - エンタープライズ層: 1 分あたり 10000 リクエスト
  version: 2.0.0
  contact:
    name: API Support
    email: api-support@example.com
    url: https://docs.example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v2
    description: Production
  - url: https://staging-api.example.com/v2
    description: Staging
  - url: http://localhost:3000/v2
    description: Local development

tags:
  - name: Users
    description: ユーザー管理操作
  - name: Profiles
    description: ユーザープロフィール操作
  - name: Admin
    description: 管理者操作

paths:
  /users:
    get:
      operationId: listUsers
      summary: すべてのユーザーを一覧表示
      description: オプションのフィルタリング機能付きでページネーション化されたユーザーリストを返します。
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
        - name: status
          in: query
          description: ユーザーステータスでフィルタ
          schema:
            $ref: "#/components/schemas/UserStatus"
        - name: search
          in: query
          description: 名前またはメールアドレスで検索
          schema:
            type: string
            minLength: 2
            maxLength: 100
      responses:
        "200":
          description: 成功レスポンス
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
              examples:
                default:
                  $ref: "#/components/examples/UserListExample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
      security:
        - bearerAuth: []

    post:
      operationId: createUser
      summary: 新規ユーザーを作成
      description: 新しいユーザーアカウントを作成し、ウェルカムメールを送信します。
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
            examples:
              standard:
                summary: 標準ユーザー
                value:
                  email: user@example.com
                  name: John Doe
                  role: user
              admin:
                summary: 管理者ユーザー
                value:
                  email: admin@example.com
                  name: Admin User
                  role: admin
      responses:
        "201":
          description: ユーザーが正常に作成されました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
          headers:
            Location:
              description: 作成されたユーザーの URL
              schema:
                type: string
                format: uri
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          description: メールアドレスが既に存在します
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - bearerAuth: []

  /users/{userId}:
    parameters:
      - $ref: "#/components/parameters/UserIdParam"

    get:
      operationId: getUser
      summary: ID でユーザーを取得
      tags:
        - Users
      responses:
        "200":
          description: 成功レスポンス
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - bearerAuth: []

    patch:
      operationId: updateUser
      summary: ユーザーを更新
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: ユーザーが更新されました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - bearerAuth: []

    delete:
      operationId: deleteUser
      summary: ユーザーを削除
      tags:
        - Users
        - Admin
      responses:
        "204":
          description: ユーザーが削除されました
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - bearerAuth: []
        - apiKey: []

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - name
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: ユーザーの一意識別子
        email:
          type: string
          format: email
          description: ユーザーのメールアドレス
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: ユーザーの表示名
        status:
          $ref: "#/components/schemas/UserStatus"
        role:
          type: string
          enum: [user, moderator, admin]
          default: user
        avatar:
          type: string
          format: uri
          nullable: true
        metadata:
          type: object
          additionalProperties: true
          description: カスタムメタデータ
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    UserStatus:
      type: string
      enum: [active, inactive, suspended, pending]
      description: ユーザーアカウントのステータス

    CreateUserRequest:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 100
        role:
          type: string
          enum: [user, moderator, admin]
          default: user
        metadata:
          type: object
          additionalProperties: true

    UpdateUserRequest:
      type: object
      minProperties: 1
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        status:
          $ref: "#/components/schemas/UserStatus"
        role:
          type: string
          enum: [user, moderator, admin]
        metadata:
          type: object
          additionalProperties: true

    UserListResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/User"
        pagination:
          $ref: "#/components/schemas/Pagination"

    Pagination:
      type: object
      required:
        - page
        - limit
        - total
        - totalPages
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
        total:
          type: integer
          minimum: 0
        totalPages:
          type: integer
          minimum: 0
        hasNext:
          type: boolean
        hasPrev:
          type: boolean

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: プログラム処理用エラーコード
        message:
          type: string
          description: 人間が読めるエラーメッセージ
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
        requestId:
          type: string
          description: サポート用リクエスト ID

  parameters:
    UserIdParam:
      name: userId
      in: path
      required: true
      description: ユーザー ID
      schema:
        type: string
        format: uuid

    PageParam:
      name: page
      in: query
      description: ページ番号（1 から開始）
      schema:
        type: integer
        minimum: 1
        default: 1

    LimitParam:
      name: limit
      in: query
      description: 1 ページあたりのアイテム数
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

  responses:
    BadRequest:
      description: 無効なリクエスト
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: VALIDATION_ERROR
            message: リクエストパラメータが無効です
            details:
              - field: email
                message: 有効なメールアドレスである必要があります

    Unauthorized:
      description: 認証が必要です
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: UNAUTHORIZED
            message: 認証が必要です

    NotFound:
      description: リソースが見つかりません
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: NOT_FOUND
            message: ユーザーが見つかりません

    RateLimited:
      description: リクエストが多すぎます
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      headers:
        Retry-After:
          description: レート制限がリセットされるまでの秒数
          schema:
            type: integer
        X-RateLimit-Limit:
          description: ウィンドウ単位のリクエスト制限
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: ウィンドウ内の残りリクエスト数
          schema:
            type: integer

  examples:
    UserListExample:
      value:
        data:
          - id: "550e8400-e29b-41d4-a716-446655440000"
            email: "john@example.com"
            name: "John Doe"
            status: "active"
            role: "user"
            createdAt: "2024-01-15T10:30:00Z"
        pagination:
          page: 1
          limit: 20
          total: 1
          totalPages: 1
          hasNext: false
          hasPrev: false

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: /auth/login から取得した JWT トークン

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: サービス間通信用 API キー

security:
  - bearerAuth: []

高度なコードファースト生成パターンとツール化については、references/code-first-and-tooling.md をご覧ください:

テンプレート 2: Python/FastAPI — Field 検証を備えた Pydantic モデル、enum 型、response_model と status_code を使用した完全な CRUD エンドポイント、仕様を JSON として出力
テンプレート 3: TypeScript/tsoa — デコレータベースのコントローラー（@Route、@Get、@Security、@Example、@Response）で TypeScript 型から OpenAPI を生成
テンプレート 4: 検証とリント — operationId、セキュリティ、命名規則のカスタムルール付き Spectral ルールセット（.spectral.yaml）、MIME タイプ強制とコードサンプル生成を備えた Redocly 設定
SDK 生成 — TypeScript（fetch）、Python、Go クライアント用の openapi-generator-cli

ベストプラクティス

すべきこと

$ref を使用 — スキーマ、パラメータ、レスポンスを再利用する
例を追加 — 実世界の値は利用者に役立つ
エラーを文書化 — すべての可能なエラーコード
API をバージョニング — URL またはヘッダーで
セマンティックバージョニングを使用 — 仕様変更の場合

すべきでないこと

汎用的な説明は避ける — 具体的に
セキュリティをスキップしない — すべてのスキームを定義する
null を忘れない — null 可能性を明確に
スタイルを混在させない — 全体で一貫した命名
URL をハードコードしない — サーバー変数を使用する

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

詳細情報

作者: wshobson
リポジトリ: wshobson/agents
ライセンス: MIT
最終更新: 不明

GitHubで原本を見る →フィードバックを送る

Source: https://github.com/wshobson/agents / ライセンス: MIT

openapi-spec-generation

SKILL.md 本文

OpenAPI 仕様生成

このスキルを使う場面

コア概念

1. OpenAPI 3.1 構造

2. デザインアプローチ

テンプレート

テンプレート 1: 完全な API 仕様

ベストプラクティス

すべきこと

すべきでないこと

詳細情報

関連スキル

doubt-driven-development

apprun-skills

desloppify

debugging-and-error-recovery

test-driven-development

incremental-implementation