[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72XP8HMQ2EMEX326GVA6V0C":3,"skill-same:01M72XP8HMQ2EMEX326GVA6V0C":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M72XP8HMQ2EMEX326GVA6V0C","openapi-spec-generation",null,"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.","steph-frtech\u002Fclaude-code-up","steph-frtech","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F198466323?v=4","01M72XD213FVQA2QXRGTJFKHE1","01M72XD227AANJ993SQTNZB1CK",1,"MIT","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fmarketplaces\u002Fwshobson\u002Fplugins\u002Fdocumentation-generation\u002Fskills\u002Fopenapi-spec-generation\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: openapi-spec-generation\ndescription: 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.\n---\n\n# OpenAPI Spec Generation\n\nComprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.\n\n## When to Use This Skill\n\n- Creating API documentation from scratch\n- Generating OpenAPI specs from existing code\n- Designing API contracts (design-first approach)\n- Validating API implementations against specs\n- Generating client SDKs from specs\n- Setting up API documentation portals\n\n## Core Concepts\n\n### 1. OpenAPI 3.1 Structure\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: API Title\n  version: 1.0.0\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv1\npaths:\n  \u002Fresources:\n    get: ...\ncomponents:\n  schemas: ...\n  securitySchemes: ...\n```\n\n### 2. Design Approaches\n\n| Approach         | Description                  | Best For            |\n| ---------------- | ---------------------------- | ------------------- |\n| **Design-First** | Write spec before code       | New APIs, contracts |\n| **Code-First**   | Generate spec from code      | Existing APIs       |\n| **Hybrid**       | Annotate code, generate spec | Evolving APIs       |\n\n## Templates\n\n### Template 1: Complete API Specification\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: User Management API\n  description: |\n    API for managing users and their profiles.\n\n    ## Authentication\n    All endpoints require Bearer token authentication.\n\n    ## Rate Limiting\n    - 1000 requests per minute for standard tier\n    - 10000 requests per minute for enterprise tier\n  version: 2.0.0\n  contact:\n    name: API Support\n    email: api-support@example.com\n    url: https:\u002F\u002Fdocs.example.com\n  license:\n    name: MIT\n    url: https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT\n\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv2\n    description: Production\n  - url: https:\u002F\u002Fstaging-api.example.com\u002Fv2\n    description: Staging\n  - url: http:\u002F\u002Flocalhost:3000\u002Fv2\n    description: Local development\n\ntags:\n  - name: Users\n    description: User management operations\n  - name: Profiles\n    description: User profile operations\n  - name: Admin\n    description: Administrative operations\n\npaths:\n  \u002Fusers:\n    get:\n      operationId: listUsers\n      summary: List all users\n      description: Returns a paginated list of users with optional filtering.\n      tags:\n        - Users\n      parameters:\n        - $ref: \"#\u002Fcomponents\u002Fparameters\u002FPageParam\"\n        - $ref: \"#\u002Fcomponents\u002Fparameters\u002FLimitParam\"\n        - name: status\n          in: query\n          description: Filter by user status\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FUserStatus\"\n        - name: search\n          in: query\n          description: Search by name or email\n          schema:\n            type: string\n            minLength: 2\n            maxLength: 100\n      responses:\n        \"200\":\n          description: Successful response\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FUserListResponse\"\n              examples:\n                default:\n                  $ref: \"#\u002Fcomponents\u002Fexamples\u002FUserListExample\"\n        \"400\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FBadRequest\"\n        \"401\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FUnauthorized\"\n        \"429\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FRateLimited\"\n      security:\n        - bearerAuth: []\n\n    post:\n      operationId: createUser\n      summary: Create a new user\n      description: Creates a new user account and sends welcome email.\n      tags:\n        - Users\n      requestBody:\n        required: true\n        content:\n          application\u002Fjson:\n            schema:\n              $ref: \"#\u002Fcomponents\u002Fschemas\u002FCreateUserRequest\"\n            examples:\n              standard:\n                summary: Standard user\n                value:\n                  email: user@example.com\n                  name: John Doe\n                  role: user\n              admin:\n                summary: Admin user\n                value:\n                  email: admin@example.com\n                  name: Admin User\n                  role: admin\n      responses:\n        \"201\":\n          description: User created successfully\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FUser\"\n          headers:\n            Location:\n              description: URL of created user\n              schema:\n                type: string\n                format: uri\n        \"400\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FBadRequest\"\n        \"409\":\n          description: Email already exists\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n      security:\n        - bearerAuth: []\n\n  \u002Fusers\u002F{userId}:\n    parameters:\n      - $ref: \"#\u002Fcomponents\u002Fparameters\u002FUserIdParam\"\n\n    get:\n      operationId: getUser\n      summary: Get user by ID\n      tags:\n        - Users\n      responses:\n        \"200\":\n          description: Successful response\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FUser\"\n        \"404\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FNotFound\"\n      security:\n        - bearerAuth: []\n\n    patch:\n      operationId: updateUser\n      summary: Update user\n      tags:\n        - Users\n      requestBody:\n        required: true\n        content:\n          application\u002Fjson:\n            schema:\n              $ref: \"#\u002Fcomponents\u002Fschemas\u002FUpdateUserRequest\"\n      responses:\n        \"200\":\n          description: User updated\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FUser\"\n        \"400\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FBadRequest\"\n        \"404\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FNotFound\"\n      security:\n        - bearerAuth: []\n\n    delete:\n      operationId: deleteUser\n      summary: Delete user\n      tags:\n        - Users\n        - Admin\n      responses:\n        \"204\":\n          description: User deleted\n        \"404\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FNotFound\"\n      security:\n        - bearerAuth: []\n        - apiKey: []\n\ncomponents:\n  schemas:\n    User:\n      type: object\n      required:\n        - id\n        - email\n        - name\n        - status\n        - createdAt\n      properties:\n        id:\n          type: string\n          format: uuid\n          readOnly: true\n          description: Unique user identifier\n        email:\n          type: string\n          format: email\n          description: User email address\n        name:\n          type: string\n          minLength: 1\n          maxLength: 100\n          description: User display name\n        status:\n          $ref: \"#\u002Fcomponents\u002Fschemas\u002FUserStatus\"\n        role:\n          type: string\n          enum: [user, moderator, admin]\n          default: user\n        avatar:\n          type: string\n          format: uri\n          nullable: true\n        metadata:\n          type: object\n          additionalProperties: true\n          description: Custom metadata\n        createdAt:\n          type: string\n          format: date-time\n          readOnly: true\n        updatedAt:\n          type: string\n          format: date-time\n          readOnly: true\n\n    UserStatus:\n      type: string\n      enum: [active, inactive, suspended, pending]\n      description: User account status\n\n    CreateUserRequest:\n      type: object\n      required:\n        - email\n        - name\n      properties:\n        email:\n          type: string\n          format: email\n        name:\n          type: string\n          minLength: 1\n          maxLength: 100\n        role:\n          type: string\n          enum: [user, moderator, admin]\n          default: user\n        metadata:\n          type: object\n          additionalProperties: true\n\n    UpdateUserRequest:\n      type: object\n      minProperties: 1\n      properties:\n        name:\n          type: string\n          minLength: 1\n          maxLength: 100\n        status:\n          $ref: \"#\u002Fcomponents\u002Fschemas\u002FUserStatus\"\n        role:\n          type: string\n          enum: [user, moderator, admin]\n        metadata:\n          type: object\n          additionalProperties: true\n\n    UserListResponse:\n      type: object\n      required:\n        - data\n        - pagination\n      properties:\n        data:\n          type: array\n          items:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FUser\"\n        pagination:\n          $ref: \"#\u002Fcomponents\u002Fschemas\u002FPagination\"\n\n    Pagination:\n      type: object\n      required:\n        - page\n        - limit\n        - total\n        - totalPages\n      properties:\n        page:\n          type: integer\n          minimum: 1\n        limit:\n          type: integer\n          minimum: 1\n          maximum: 100\n        total:\n          type: integer\n          minimum: 0\n        totalPages:\n          type: integer\n          minimum: 0\n        hasNext:\n          type: boolean\n        hasPrev:\n          type: boolean\n\n    Error:\n      type: object\n      required:\n        - code\n        - message\n      properties:\n        code:\n          type: string\n          description: Error code for programmatic handling\n        message:\n          type: string\n          description: Human-readable error message\n        details:\n          type: array\n          items:\n            type: object\n            properties:\n              field:\n                type: string\n              message:\n                type: string\n        requestId:\n          type: string\n          description: Request ID for support\n\n  parameters:\n    UserIdParam:\n      name: userId\n      in: path\n      required: true\n      description: User ID\n      schema:\n        type: string\n        format: uuid\n\n    PageParam:\n      name: page\n      in: query\n      description: Page number (1-based)\n      schema:\n        type: integer\n        minimum: 1\n        default: 1\n\n    LimitParam:\n      name: limit\n      in: query\n      description: Items per page\n      schema:\n        type: integer\n        minimum: 1\n        maximum: 100\n        default: 20\n\n  responses:\n    BadRequest:\n      description: Invalid request\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n          example:\n            code: VALIDATION_ERROR\n            message: Invalid request parameters\n            details:\n              - field: email\n                message: Must be a valid email address\n\n    Unauthorized:\n      description: Authentication required\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n          example:\n            code: UNAUTHORIZED\n            message: Authentication required\n\n    NotFound:\n      description: Resource not found\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n          example:\n            code: NOT_FOUND\n            message: User not found\n\n    RateLimited:\n      description: Too many requests\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n      headers:\n        Retry-After:\n          description: Seconds until rate limit resets\n          schema:\n            type: integer\n        X-RateLimit-Limit:\n          description: Request limit per window\n          schema:\n            type: integer\n        X-RateLimit-Remaining:\n          description: Remaining requests in window\n          schema:\n            type: integer\n\n  examples:\n    UserListExample:\n      value:\n        data:\n          - id: \"550e8400-e29b-41d4-a716-446655440000\"\n            email: \"john@example.com\"\n            name: \"John Doe\"\n            status: \"active\"\n            role: \"user\"\n            createdAt: \"2024-01-15T10:30:00Z\"\n        pagination:\n          page: 1\n          limit: 20\n          total: 1\n          totalPages: 1\n          hasNext: false\n          hasPrev: false\n\n  securitySchemes:\n    bearerAuth:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n      description: JWT token from \u002Fauth\u002Flogin\n\n    apiKey:\n      type: apiKey\n      in: header\n      name: X-API-Key\n      description: API key for service-to-service calls\n\nsecurity:\n  - bearerAuth: []\n```\n\nFor advanced code-first generation patterns and tooling, see [references\u002Fcode-first-and-tooling.md](references\u002Fcode-first-and-tooling.md):\n\n- **Template 2: Python\u002FFastAPI** — Pydantic models with `Field` validation, enum types, full CRUD endpoints with `response_model` and `status_code`, exporting the spec as JSON\n- **Template 3: TypeScript\u002Ftsoa** — Decorator-based controllers (`@Route`, `@Get`, `@Security`, `@Example`, `@Response`) that generate OpenAPI from TypeScript types\n- **Template 4: Validation & Linting** — Spectral ruleset (`.spectral.yaml`) with custom rules for operationId, security, naming conventions; Redocly config with MIME type enforcement and code sample generation\n- **SDK Generation** — `openapi-generator-cli` for TypeScript (fetch), Python, and Go clients\n\n## Best Practices\n\n### Do's\n\n- **Use $ref** - Reuse schemas, parameters, responses\n- **Add examples** - Real-world values help consumers\n- **Document errors** - All possible error codes\n- **Version your API** - In URL or header\n- **Use semantic versioning** - For spec changes\n\n### Don'ts\n\n- **Don't use generic descriptions** - Be specific\n- **Don't skip security** - Define all schemes\n- **Don't forget nullable** - Be explicit about null\n- **Don't mix styles** - Consistent naming throughout\n- **Don't hardcode URLs** - Use server variables\n","# OpenAPI Spec Generation\n\nComprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.\n\n## When to Use This Skill\n\n- Creating API documentation from scratch\n- Generating OpenAPI specs from existing code\n- Designing API contracts (design-first approach)\n- Validating API implementations against specs\n- Generating client SDKs from specs\n- Setting up API documentation portals\n\n## Core Concepts\n\n### 1. OpenAPI 3.1 Structure\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: API Title\n  version: 1.0.0\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv1\npaths:\n  \u002Fresources:\n    get: ...\ncomponents:\n  schemas: ...\n  securitySchemes: ...\n```\n\n### 2. Design Approaches\n\n| Approach         | Description                  | Best For            |\n| ---------------- | ---------------------------- | ------------------- |\n| **Design-First** | Write spec before code       | New APIs, contracts |\n| **Code-First**   | Generate spec from code      | Existing APIs       |\n| **Hybrid**       | Annotate code, generate spec | Evolving APIs       |\n\n## Templates\n\n### Template 1: Complete API Specification\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: User Management API\n  description: |\n    API for managing users and their profiles.\n\n    ## Authentication\n    All endpoints require Bearer token authentication.\n\n    ## Rate Limiting\n    - 1000 requests per minute for standard tier\n    - 10000 requests per minute for enterprise tier\n  version: 2.0.0\n  contact:\n    name: API Support\n    email: api-support@example.com\n    url: https:\u002F\u002Fdocs.example.com\n  license:\n    name: MIT\n    url: https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT\n\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv2\n    description: Production\n  - url: https:\u002F\u002Fstaging-api.example.com\u002Fv2\n    description: Staging\n  - url: http:\u002F\u002Flocalhost:3000\u002Fv2\n    description: Local development\n\ntags:\n  - name: Users\n    description: User management operations\n  - name: Profiles\n    description: User profile operations\n  - name: Admin\n    description: Administrative operations\n\npaths:\n  \u002Fusers:\n    get:\n      operationId: listUsers\n      summary: List all users\n      description: Returns a paginated list of users with optional filtering.\n      tags:\n        - Users\n      parameters:\n        - $ref: \"#\u002Fcomponents\u002Fparameters\u002FPageParam\"\n        - $ref: \"#\u002Fcomponents\u002Fparameters\u002FLimitParam\"\n        - name: status\n          in: query\n          description: Filter by user status\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FUserStatus\"\n        - name: search\n          in: query\n          description: Search by name or email\n          schema:\n            type: string\n            minLength: 2\n            maxLength: 100\n      responses:\n        \"200\":\n          description: Successful response\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FUserListResponse\"\n              examples:\n                default:\n                  $ref: \"#\u002Fcomponents\u002Fexamples\u002FUserListExample\"\n        \"400\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FBadRequest\"\n        \"401\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FUnauthorized\"\n        \"429\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FRateLimited\"\n      security:\n        - bearerAuth: []\n\n    post:\n      operationId: createUser\n      summary: Create a new user\n      description: Creates a new user account and sends welcome email.\n      tags:\n        - Users\n      requestBody:\n        required: true\n        content:\n          application\u002Fjson:\n            schema:\n              $ref: \"#\u002Fcomponents\u002Fschemas\u002FCreateUserRequest\"\n            examples:\n              standard:\n                summary: Standard user\n                value:\n                  email: user@example.com\n                  name: John Doe\n                  role: user\n              admin:\n                summary: Admin user\n                value:\n                  email: admin@example.com\n                  name: Admin User\n                  role: admin\n      responses:\n        \"201\":\n          description: User created successfully\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FUser\"\n          headers:\n            Location:\n              description: URL of created user\n              schema:\n                type: string\n                format: uri\n        \"400\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FBadRequest\"\n        \"409\":\n          description: Email already exists\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n      security:\n        - bearerAuth: []\n\n  \u002Fusers\u002F{userId}:\n    parameters:\n      - $ref: \"#\u002Fcomponents\u002Fparameters\u002FUserIdParam\"\n\n    get:\n      operationId: getUser\n      summary: Get user by ID\n      tags:\n        - Users\n      responses:\n        \"200\":\n          description: Successful response\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FUser\"\n        \"404\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FNotFound\"\n      security:\n        - bearerAuth: []\n\n    patch:\n      operationId: updateUser\n      summary: Update user\n      tags:\n        - Users\n      requestBody:\n        required: true\n        content:\n          application\u002Fjson:\n            schema:\n              $ref: \"#\u002Fcomponents\u002Fschemas\u002FUpdateUserRequest\"\n      responses:\n        \"200\":\n          description: User updated\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: \"#\u002Fcomponents\u002Fschemas\u002FUser\"\n        \"400\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FBadRequest\"\n        \"404\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FNotFound\"\n      security:\n        - bearerAuth: []\n\n    delete:\n      operationId: deleteUser\n      summary: Delete user\n      tags:\n        - Users\n        - Admin\n      responses:\n        \"204\":\n          description: User deleted\n        \"404\":\n          $ref: \"#\u002Fcomponents\u002Fresponses\u002FNotFound\"\n      security:\n        - bearerAuth: []\n        - apiKey: []\n\ncomponents:\n  schemas:\n    User:\n      type: object\n      required:\n        - id\n        - email\n        - name\n        - status\n        - createdAt\n      properties:\n        id:\n          type: string\n          format: uuid\n          readOnly: true\n          description: Unique user identifier\n        email:\n          type: string\n          format: email\n          description: User email address\n        name:\n          type: string\n          minLength: 1\n          maxLength: 100\n          description: User display name\n        status:\n          $ref: \"#\u002Fcomponents\u002Fschemas\u002FUserStatus\"\n        role:\n          type: string\n          enum: [user, moderator, admin]\n          default: user\n        avatar:\n          type: string\n          format: uri\n          nullable: true\n        metadata:\n          type: object\n          additionalProperties: true\n          description: Custom metadata\n        createdAt:\n          type: string\n          format: date-time\n          readOnly: true\n        updatedAt:\n          type: string\n          format: date-time\n          readOnly: true\n\n    UserStatus:\n      type: string\n      enum: [active, inactive, suspended, pending]\n      description: User account status\n\n    CreateUserRequest:\n      type: object\n      required:\n        - email\n        - name\n      properties:\n        email:\n          type: string\n          format: email\n        name:\n          type: string\n          minLength: 1\n          maxLength: 100\n        role:\n          type: string\n          enum: [user, moderator, admin]\n          default: user\n        metadata:\n          type: object\n          additionalProperties: true\n\n    UpdateUserRequest:\n      type: object\n      minProperties: 1\n      properties:\n        name:\n          type: string\n          minLength: 1\n          maxLength: 100\n        status:\n          $ref: \"#\u002Fcomponents\u002Fschemas\u002FUserStatus\"\n        role:\n          type: string\n          enum: [user, moderator, admin]\n        metadata:\n          type: object\n          additionalProperties: true\n\n    UserListResponse:\n      type: object\n      required:\n        - data\n        - pagination\n      properties:\n        data:\n          type: array\n          items:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FUser\"\n        pagination:\n          $ref: \"#\u002Fcomponents\u002Fschemas\u002FPagination\"\n\n    Pagination:\n      type: object\n      required:\n        - page\n        - limit\n        - total\n        - totalPages\n      properties:\n        page:\n          type: integer\n          minimum: 1\n        limit:\n          type: integer\n          minimum: 1\n          maximum: 100\n        total:\n          type: integer\n          minimum: 0\n        totalPages:\n          type: integer\n          minimum: 0\n        hasNext:\n          type: boolean\n        hasPrev:\n          type: boolean\n\n    Error:\n      type: object\n      required:\n        - code\n        - message\n      properties:\n        code:\n          type: string\n          description: Error code for programmatic handling\n        message:\n          type: string\n          description: Human-readable error message\n        details:\n          type: array\n          items:\n            type: object\n            properties:\n              field:\n                type: string\n              message:\n                type: string\n        requestId:\n          type: string\n          description: Request ID for support\n\n  parameters:\n    UserIdParam:\n      name: userId\n      in: path\n      required: true\n      description: User ID\n      schema:\n        type: string\n        format: uuid\n\n    PageParam:\n      name: page\n      in: query\n      description: Page number (1-based)\n      schema:\n        type: integer\n        minimum: 1\n        default: 1\n\n    LimitParam:\n      name: limit\n      in: query\n      description: Items per page\n      schema:\n        type: integer\n        minimum: 1\n        maximum: 100\n        default: 20\n\n  responses:\n    BadRequest:\n      description: Invalid request\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n          example:\n            code: VALIDATION_ERROR\n            message: Invalid request parameters\n            details:\n              - field: email\n                message: Must be a valid email address\n\n    Unauthorized:\n      description: Authentication required\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n          example:\n            code: UNAUTHORIZED\n            message: Authentication required\n\n    NotFound:\n      description: Resource not found\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n          example:\n            code: NOT_FOUND\n            message: User not found\n\n    RateLimited:\n      description: Too many requests\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: \"#\u002Fcomponents\u002Fschemas\u002FError\"\n      headers:\n        Retry-After:\n          description: Seconds until rate limit resets\n          schema:\n            type: integer\n        X-RateLimit-Limit:\n          description: Request limit per window\n          schema:\n            type: integer\n        X-RateLimit-Remaining:\n          description: Remaining requests in window\n          schema:\n            type: integer\n\n  examples:\n    UserListExample:\n      value:\n        data:\n          - id: \"550e8400-e29b-41d4-a716-446655440000\"\n            email: \"john@example.com\"\n            name: \"John Doe\"\n            status: \"active\"\n            role: \"user\"\n            createdAt: \"2024-01-15T10:30:00Z\"\n        pagination:\n          page: 1\n          limit: 20\n          total: 1\n          totalPages: 1\n          hasNext: false\n          hasPrev: false\n\n  securitySchemes:\n    bearerAuth:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n      description: JWT token from \u002Fauth\u002Flogin\n\n    apiKey:\n      type: apiKey\n      in: header\n      name: X-API-Key\n      description: API key for service-to-service calls\n\nsecurity:\n  - bearerAuth: []\n```\n\nFor advanced code-first generation patterns and tooling, see [references\u002Fcode-first-and-tooling.md](references\u002Fcode-first-and-tooling.md):\n\n- **Template 2: Python\u002FFastAPI** — Pydantic models with `Field` validation, enum types, full CRUD endpoints with `response_model` and `status_code`, exporting the spec as JSON\n- **Template 3: TypeScript\u002Ftsoa** — Decorator-based controllers (`@Route`, `@Get`, `@Security`, `@Example`, `@Response`) that generate OpenAPI from TypeScript types\n- **Template 4: Validation & Linting** — Spectral ruleset (`.spectral.yaml`) with custom rules for operationId, security, naming conventions; Redocly config with MIME type enforcement and code sample generation\n- **SDK Generation** — `openapi-generator-cli` for TypeScript (fetch), Python, and Go clients\n\n## Best Practices\n\n### Do's\n\n- **Use $ref** - Reuse schemas, parameters, responses\n- **Add examples** - Real-world values help consumers\n- **Document errors** - All possible error codes\n- **Version your API** - In URL or header\n- **Use semantic versioning** - For spec changes\n\n### Don'ts\n\n- **Don't use generic descriptions** - Be specific\n- **Don't skip security** - Define all schemes\n- **Don't forget nullable** - Be explicit about null\n- **Don't mix styles** - Consistent naming throughout\n- **Don't hardcode URLs** - Use server variables\n",{"name":5,"description":7},"main","900bb95bbe72cdb94af6f5a620aa5081264b7b6d",".claude\u002Fmarketplaces\u002Fwshobson\u002Fplugins\u002Fdocumentation-generation\u002Fskills\u002Fopenapi-spec-generation",0,"https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up#readme","https:\u002F\u002Fgithub.com\u002Fsteph-frtech","2026-05-16 00:03:30",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add steph-frtech\u002Fclaude-code-up --skill openapi-spec-generation",{"tool":37,"command":38},"bunx","bunx skills add steph-frtech\u002Fclaude-code-up --skill openapi-spec-generation",{"tool":40,"command":41},"pnpm","pnpm dlx skills add steph-frtech\u002Fclaude-code-up --skill openapi-spec-generation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fmarketplaces\u002Fwshobson\u002Fplugins\u002Fdocumentation-generation\u002Fskills\u002Fopenapi-spec-generation\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fcode-first-and-tooling.md","REFERENCE","参考文档",11762,"https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fmarketplaces\u002Fwshobson\u002Fplugins\u002Fdocumentation-generation\u002Fskills\u002Fopenapi-spec-generation\u002Freferences\u002Fcode-first-and-tooling.md",[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M72Y1BY6X8TX3DS19Y04NEBQ","example","One-line summary of what this skill does","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002Fskills\u002Fexample\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M72Y1A38EYR8S9P1MBYDAQTW","writing-plans","Use when you have a spec or requirements for a multi-step task, before touching code","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__writing-plans\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M72Y174QSV1B5NV1E4KWHQBR","using-git-worktrees","Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__using-git-worktrees\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M72Y14SQRHHMKG316HGB2CGK","test-driven-development","Use when implementing any feature or bugfix, before writing implementation code","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__test-driven-development\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M72Y127BCPRH3BRKPJC3Q3G2","systematic-debugging","Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__systematic-debugging\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":18},"01M72Y1090GJA6B67KPD60WPHH","subagent-driven-development","Use when executing implementation plans with independent tasks in the current session","https:\u002F\u002Fgithub.com\u002Fsteph-frtech\u002Fclaude-code-up\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsuperpowers__subagent-driven-development\u002FSKILL.md",[],[]]