[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7BWDBB549AV5XRRAZT48H8H":3,"skill-same:01M7BWDBB549AV5XRRAZT48H8H":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7BWDBB549AV5XRRAZT48H8H","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.","YYC-Cube\u002FYYC3-Knowledge-Base","YYC-Cube","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F235006543?v=4","01M79J2PH4SWD2X0825X6PN748","yyc3","01M79J2PHVK3F6ZBYT8K2SCZCW",1,"MIT","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-Plugin-插件协议\u002FYYC3-Plugin-插件协议-plugins-claude\u002Fdocumentation-generation\u002Fskills\u002Fopenapi-spec-generation\u002FSKILL.md",[],[],"2026-11-15 14:19:17",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\n### Template 2: Code-First Generation (Python\u002FFastAPI)\n\n```python\n# FastAPI with automatic OpenAPI generation\nfrom fastapi import FastAPI, HTTPException, Query, Path, Depends\nfrom pydantic import BaseModel, Field, EmailStr\nfrom typing import Optional, List\nfrom datetime import datetime\nfrom uuid import UUID\nfrom enum import Enum\n\napp = FastAPI(\n    title=\"User Management API\",\n    description=\"API for managing users and profiles\",\n    version=\"2.0.0\",\n    openapi_tags=[\n        {\"name\": \"Users\", \"description\": \"User operations\"},\n        {\"name\": \"Profiles\", \"description\": \"Profile operations\"},\n    ],\n    servers=[\n        {\"url\": \"https:\u002F\u002Fapi.example.com\u002Fv2\", \"description\": \"Production\"},\n        {\"url\": \"http:\u002F\u002Flocalhost:8000\", \"description\": \"Development\"},\n    ],\n)\n\n# Enums\nclass UserStatus(str, Enum):\n    active = \"active\"\n    inactive = \"inactive\"\n    suspended = \"suspended\"\n    pending = \"pending\"\n\nclass UserRole(str, Enum):\n    user = \"user\"\n    moderator = \"moderator\"\n    admin = \"admin\"\n\n# Models\nclass UserBase(BaseModel):\n    email: EmailStr = Field(..., description=\"User email address\")\n    name: str = Field(..., min_length=1, max_length=100, description=\"Display name\")\n\nclass UserCreate(UserBase):\n    role: UserRole = Field(default=UserRole.user)\n    metadata: Optional[dict] = Field(default=None, description=\"Custom metadata\")\n\n    model_config = {\n        \"json_schema_extra\": {\n            \"examples\": [\n                {\n                    \"email\": \"user@example.com\",\n                    \"name\": \"John Doe\",\n                    \"role\": \"user\"\n                }\n            ]\n        }\n    }\n\nclass UserUpdate(BaseModel):\n    name: Optional[str] = Field(None, min_length=1, max_length=100)\n    status: Optional[UserStatus] = None\n    role: Optional[UserRole] = None\n    metadata: Optional[dict] = None\n\nclass User(UserBase):\n    id: UUID = Field(..., description=\"Unique identifier\")\n    status: UserStatus\n    role: UserRole\n    avatar: Optional[str] = Field(None, description=\"Avatar URL\")\n    metadata: Optional[dict] = None\n    created_at: datetime = Field(..., alias=\"createdAt\")\n    updated_at: Optional[datetime] = Field(None, alias=\"updatedAt\")\n\n    model_config = {\"populate_by_name\": True}\n\nclass Pagination(BaseModel):\n    page: int = Field(..., ge=1)\n    limit: int = Field(..., ge=1, le=100)\n    total: int = Field(..., ge=0)\n    total_pages: int = Field(..., ge=0, alias=\"totalPages\")\n    has_next: bool = Field(..., alias=\"hasNext\")\n    has_prev: bool = Field(..., alias=\"hasPrev\")\n\nclass UserListResponse(BaseModel):\n    data: List[User]\n    pagination: Pagination\n\nclass ErrorDetail(BaseModel):\n    field: str\n    message: str\n\nclass ErrorResponse(BaseModel):\n    code: str = Field(..., description=\"Error code\")\n    message: str = Field(..., description=\"Error message\")\n    details: Optional[List[ErrorDetail]] = None\n    request_id: Optional[str] = Field(None, alias=\"requestId\")\n\n# Endpoints\n@app.get(\n    \"\u002Fusers\",\n    response_model=UserListResponse,\n    tags=[\"Users\"],\n    summary=\"List all users\",\n    description=\"Returns a paginated list of users with optional filtering.\",\n    responses={\n        400: {\"model\": ErrorResponse, \"description\": \"Invalid request\"},\n        401: {\"model\": ErrorResponse, \"description\": \"Unauthorized\"},\n    },\n)\nasync def list_users(\n    page: int = Query(1, ge=1, description=\"Page number\"),\n    limit: int = Query(20, ge=1, le=100, description=\"Items per page\"),\n    status: Optional[UserStatus] = Query(None, description=\"Filter by status\"),\n    search: Optional[str] = Query(None, min_length=2, max_length=100),\n):\n    \"\"\"\n    List users with pagination and filtering.\n\n    - **page**: Page number (1-based)\n    - **limit**: Number of items per page (max 100)\n    - **status**: Filter by user status\n    - **search**: Search by name or email\n    \"\"\"\n    # Implementation\n    pass\n\n@app.post(\n    \"\u002Fusers\",\n    response_model=User,\n    status_code=201,\n    tags=[\"Users\"],\n    summary=\"Create a new user\",\n    responses={\n        400: {\"model\": ErrorResponse},\n        409: {\"model\": ErrorResponse, \"description\": \"Email already exists\"},\n    },\n)\nasync def create_user(user: UserCreate):\n    \"\"\"Create a new user and send welcome email.\"\"\"\n    pass\n\n@app.get(\n    \"\u002Fusers\u002F{user_id}\",\n    response_model=User,\n    tags=[\"Users\"],\n    summary=\"Get user by ID\",\n    responses={404: {\"model\": ErrorResponse}},\n)\nasync def get_user(\n    user_id: UUID = Path(..., description=\"User ID\"),\n):\n    \"\"\"Retrieve a specific user by their ID.\"\"\"\n    pass\n\n@app.patch(\n    \"\u002Fusers\u002F{user_id}\",\n    response_model=User,\n    tags=[\"Users\"],\n    summary=\"Update user\",\n    responses={\n        400: {\"model\": ErrorResponse},\n        404: {\"model\": ErrorResponse},\n    },\n)\nasync def update_user(\n    user_id: UUID = Path(..., description=\"User ID\"),\n    user: UserUpdate = ...,\n):\n    \"\"\"Update user attributes.\"\"\"\n    pass\n\n@app.delete(\n    \"\u002Fusers\u002F{user_id}\",\n    status_code=204,\n    tags=[\"Users\", \"Admin\"],\n    summary=\"Delete user\",\n    responses={404: {\"model\": ErrorResponse}},\n)\nasync def delete_user(\n    user_id: UUID = Path(..., description=\"User ID\"),\n):\n    \"\"\"Permanently delete a user.\"\"\"\n    pass\n\n# Export OpenAPI spec\nif __name__ == \"__main__\":\n    import json\n    print(json.dumps(app.openapi(), indent=2))\n```\n\n### Template 3: Code-First (TypeScript\u002FExpress with tsoa)\n\n```typescript\n\u002F\u002F tsoa generates OpenAPI from TypeScript decorators\n\nimport {\n  Controller,\n  Get,\n  Post,\n  Patch,\n  Delete,\n  Route,\n  Path,\n  Query,\n  Body,\n  Response,\n  SuccessResponse,\n  Tags,\n  Security,\n  Example,\n} from \"tsoa\";\n\n\u002F\u002F Models\ninterface User {\n  \u002F** Unique identifier *\u002F\n  id: string;\n  \u002F** User email address *\u002F\n  email: string;\n  \u002F** Display name *\u002F\n  name: string;\n  status: UserStatus;\n  role: UserRole;\n  \u002F** Avatar URL *\u002F\n  avatar?: string;\n  \u002F** Custom metadata *\u002F\n  metadata?: Record\u003Cstring, unknown>;\n  createdAt: Date;\n  updatedAt?: Date;\n}\n\nenum UserStatus {\n  Active = \"active\",\n  Inactive = \"inactive\",\n  Suspended = \"suspended\",\n  Pending = \"pending\",\n}\n\nenum UserRole {\n  User = \"user\",\n  Moderator = \"moderator\",\n  Admin = \"admin\",\n}\n\ninterface CreateUserRequest {\n  email: string;\n  name: string;\n  role?: UserRole;\n  metadata?: Record\u003Cstring, unknown>;\n}\n\ninterface UpdateUserRequest {\n  name?: string;\n  status?: UserStatus;\n  role?: UserRole;\n  metadata?: Record\u003Cstring, unknown>;\n}\n\ninterface Pagination {\n  page: number;\n  limit: number;\n  total: number;\n  totalPages: number;\n  hasNext: boolean;\n  hasPrev: boolean;\n}\n\ninterface UserListResponse {\n  data: User[];\n  pagination: Pagination;\n}\n\ninterface ErrorResponse {\n  code: string;\n  message: string;\n  details?: { field: string; message: string }[];\n  requestId?: string;\n}\n\n@Route(\"users\")\n@Tags(\"Users\")\nexport class UsersController extends Controller {\n  \u002F**\n   * List all users with pagination and filtering\n   * @param page Page number (1-based)\n   * @param limit Items per page (max 100)\n   * @param status Filter by user status\n   * @param search Search by name or email\n   *\u002F\n  @Get()\n  @Security(\"bearerAuth\")\n  @Response\u003CErrorResponse>(400, \"Invalid request\")\n  @Response\u003CErrorResponse>(401, \"Unauthorized\")\n  @Example\u003CUserListResponse>({\n    data: [\n      {\n        id: \"550e8400-e29b-41d4-a716-446655440000\",\n        email: \"john@example.com\",\n        name: \"John Doe\",\n        status: UserStatus.Active,\n        role: UserRole.User,\n        createdAt: new Date(\"2024-01-15T10:30:00Z\"),\n      },\n    ],\n    pagination: {\n      page: 1,\n      limit: 20,\n      total: 1,\n      totalPages: 1,\n      hasNext: false,\n      hasPrev: false,\n    },\n  })\n  public async listUsers(\n    @Query() page: number = 1,\n    @Query() limit: number = 20,\n    @Query() status?: UserStatus,\n    @Query() search?: string,\n  ): Promise\u003CUserListResponse> {\n    \u002F\u002F Implementation\n    throw new Error(\"Not implemented\");\n  }\n\n  \u002F**\n   * Create a new user\n   *\u002F\n  @Post()\n  @Security(\"bearerAuth\")\n  @SuccessResponse(201, \"Created\")\n  @Response\u003CErrorResponse>(400, \"Invalid request\")\n  @Response\u003CErrorResponse>(409, \"Email already exists\")\n  public async createUser(@Body() body: CreateUserRequest): Promise\u003CUser> {\n    this.setStatus(201);\n    throw new Error(\"Not implemented\");\n  }\n\n  \u002F**\n   * Get user by ID\n   * @param userId User ID\n   *\u002F\n  @Get(\"{userId}\")\n  @Security(\"bearerAuth\")\n  @Response\u003CErrorResponse>(404, \"User not found\")\n  public async getUser(@Path() userId: string): Promise\u003CUser> {\n    throw new Error(\"Not implemented\");\n  }\n\n  \u002F**\n   * Update user attributes\n   * @param userId User ID\n   *\u002F\n  @Patch(\"{userId}\")\n  @Security(\"bearerAuth\")\n  @Response\u003CErrorResponse>(400, \"Invalid request\")\n  @Response\u003CErrorResponse>(404, \"User not found\")\n  public async updateUser(\n    @Path() userId: string,\n    @Body() body: UpdateUserRequest,\n  ): Promise\u003CUser> {\n    throw new Error(\"Not implemented\");\n  }\n\n  \u002F**\n   * Delete user\n   * @param userId User ID\n   *\u002F\n  @Delete(\"{userId}\")\n  @Tags(\"Users\", \"Admin\")\n  @Security(\"bearerAuth\")\n  @SuccessResponse(204, \"Deleted\")\n  @Response\u003CErrorResponse>(404, \"User not found\")\n  public async deleteUser(@Path() userId: string): Promise\u003Cvoid> {\n    this.setStatus(204);\n  }\n}\n```\n\n### Template 4: Validation & Linting\n\n```bash\n# Install validation tools\nnpm install -g @stoplight\u002Fspectral-cli\nnpm install -g @redocly\u002Fcli\n\n# Spectral ruleset (.spectral.yaml)\ncat > .spectral.yaml \u003C\u003C 'EOF'\nextends: [\"spectral:oas\", \"spectral:asyncapi\"]\n\nrules:\n  # Enforce operation IDs\n  operation-operationId: error\n\n  # Require descriptions\n  operation-description: warn\n  info-description: error\n\n  # Naming conventions\n  operation-operationId-valid-in-url: true\n\n  # Security\n  operation-security-defined: error\n\n  # Response codes\n  operation-success-response: error\n\n  # Custom rules\n  path-params-snake-case:\n    description: Path parameters should be snake_case\n    severity: warn\n    given: \"$.paths[*].parameters[?(@.in == 'path')].name\"\n    then:\n      function: pattern\n      functionOptions:\n        match: \"^[a-z][a-z0-9_]*$\"\n\n  schema-properties-camelCase:\n    description: Schema properties should be camelCase\n    severity: warn\n    given: \"$.components.schemas[*].properties[*]~\"\n    then:\n      function: casing\n      functionOptions:\n        type: camel\nEOF\n\n# Run Spectral\nspectral lint openapi.yaml\n\n# Redocly config (redocly.yaml)\ncat > redocly.yaml \u003C\u003C 'EOF'\nextends:\n  - recommended\n\nrules:\n  no-invalid-media-type-examples: error\n  no-invalid-schema-examples: error\n  operation-4xx-response: warn\n  request-mime-type:\n    severity: error\n    allowedValues:\n      - application\u002Fjson\n  response-mime-type:\n    severity: error\n    allowedValues:\n      - application\u002Fjson\n      - application\u002Fproblem+json\n\ntheme:\n  openapi:\n    generateCodeSamples:\n      languages:\n        - lang: curl\n        - lang: python\n        - lang: javascript\nEOF\n\n# Run Redocly\nredocly lint openapi.yaml\nredocly bundle openapi.yaml -o bundled.yaml\nredocly preview-docs openapi.yaml\n```\n\n## SDK Generation\n\n```bash\n# OpenAPI Generator\nnpm install -g @openapitools\u002Fopenapi-generator-cli\n\n# Generate TypeScript client\nopenapi-generator-cli generate \\\n  -i openapi.yaml \\\n  -g typescript-fetch \\\n  -o .\u002Fgenerated\u002Ftypescript-client \\\n  --additional-properties=supportsES6=true,npmName=@myorg\u002Fapi-client\n\n# Generate Python client\nopenapi-generator-cli generate \\\n  -i openapi.yaml \\\n  -g python \\\n  -o .\u002Fgenerated\u002Fpython-client \\\n  --additional-properties=packageName=api_client\n\n# Generate Go client\nopenapi-generator-cli generate \\\n  -i openapi.yaml \\\n  -g go \\\n  -o .\u002Fgenerated\u002Fgo-client\n```\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\n### Template 2: Code-First Generation (Python\u002FFastAPI)\n\n```python\n# FastAPI with automatic OpenAPI generation\nfrom fastapi import FastAPI, HTTPException, Query, Path, Depends\nfrom pydantic import BaseModel, Field, EmailStr\nfrom typing import Optional, List\nfrom datetime import datetime\nfrom uuid import UUID\nfrom enum import Enum\n\napp = FastAPI(\n    title=\"User Management API\",\n    description=\"API for managing users and profiles\",\n    version=\"2.0.0\",\n    openapi_tags=[\n        {\"name\": \"Users\", \"description\": \"User operations\"},\n        {\"name\": \"Profiles\", \"description\": \"Profile operations\"},\n    ],\n    servers=[\n        {\"url\": \"https:\u002F\u002Fapi.example.com\u002Fv2\", \"description\": \"Production\"},\n        {\"url\": \"http:\u002F\u002Flocalhost:8000\", \"description\": \"Development\"},\n    ],\n)\n\n# Enums\nclass UserStatus(str, Enum):\n    active = \"active\"\n    inactive = \"inactive\"\n    suspended = \"suspended\"\n    pending = \"pending\"\n\nclass UserRole(str, Enum):\n    user = \"user\"\n    moderator = \"moderator\"\n    admin = \"admin\"\n\n# Models\nclass UserBase(BaseModel):\n    email: EmailStr = Field(..., description=\"User email address\")\n    name: str = Field(..., min_length=1, max_length=100, description=\"Display name\")\n\nclass UserCreate(UserBase):\n    role: UserRole = Field(default=UserRole.user)\n    metadata: Optional[dict] = Field(default=None, description=\"Custom metadata\")\n\n    model_config = {\n        \"json_schema_extra\": {\n            \"examples\": [\n                {\n                    \"email\": \"user@example.com\",\n                    \"name\": \"John Doe\",\n                    \"role\": \"user\"\n                }\n            ]\n        }\n    }\n\nclass UserUpdate(BaseModel):\n    name: Optional[str] = Field(None, min_length=1, max_length=100)\n    status: Optional[UserStatus] = None\n    role: Optional[UserRole] = None\n    metadata: Optional[dict] = None\n\nclass User(UserBase):\n    id: UUID = Field(..., description=\"Unique identifier\")\n    status: UserStatus\n    role: UserRole\n    avatar: Optional[str] = Field(None, description=\"Avatar URL\")\n    metadata: Optional[dict] = None\n    created_at: datetime = Field(..., alias=\"createdAt\")\n    updated_at: Optional[datetime] = Field(None, alias=\"updatedAt\")\n\n    model_config = {\"populate_by_name\": True}\n\nclass Pagination(BaseModel):\n    page: int = Field(..., ge=1)\n    limit: int = Field(..., ge=1, le=100)\n    total: int = Field(..., ge=0)\n    total_pages: int = Field(..., ge=0, alias=\"totalPages\")\n    has_next: bool = Field(..., alias=\"hasNext\")\n    has_prev: bool = Field(..., alias=\"hasPrev\")\n\nclass UserListResponse(BaseModel):\n    data: List[User]\n    pagination: Pagination\n\nclass ErrorDetail(BaseModel):\n    field: str\n    message: str\n\nclass ErrorResponse(BaseModel):\n    code: str = Field(..., description=\"Error code\")\n    message: str = Field(..., description=\"Error message\")\n    details: Optional[List[ErrorDetail]] = None\n    request_id: Optional[str] = Field(None, alias=\"requestId\")\n\n# Endpoints\n@app.get(\n    \"\u002Fusers\",\n    response_model=UserListResponse,\n    tags=[\"Users\"],\n    summary=\"List all users\",\n    description=\"Returns a paginated list of users with optional filtering.\",\n    responses={\n        400: {\"model\": ErrorResponse, \"description\": \"Invalid request\"},\n        401: {\"model\": ErrorResponse, \"description\": \"Unauthorized\"},\n    },\n)\nasync def list_users(\n    page: int = Query(1, ge=1, description=\"Page number\"),\n    limit: int = Query(20, ge=1, le=100, description=\"Items per page\"),\n    status: Optional[UserStatus] = Query(None, description=\"Filter by status\"),\n    search: Optional[str] = Query(None, min_length=2, max_length=100),\n):\n    \"\"\"\n    List users with pagination and filtering.\n\n    - **page**: Page number (1-based)\n    - **limit**: Number of items per page (max 100)\n    - **status**: Filter by user status\n    - **search**: Search by name or email\n    \"\"\"\n    # Implementation\n    pass\n\n@app.post(\n    \"\u002Fusers\",\n    response_model=User,\n    status_code=201,\n    tags=[\"Users\"],\n    summary=\"Create a new user\",\n    responses={\n        400: {\"model\": ErrorResponse},\n        409: {\"model\": ErrorResponse, \"description\": \"Email already exists\"},\n    },\n)\nasync def create_user(user: UserCreate):\n    \"\"\"Create a new user and send welcome email.\"\"\"\n    pass\n\n@app.get(\n    \"\u002Fusers\u002F{user_id}\",\n    response_model=User,\n    tags=[\"Users\"],\n    summary=\"Get user by ID\",\n    responses={404: {\"model\": ErrorResponse}},\n)\nasync def get_user(\n    user_id: UUID = Path(..., description=\"User ID\"),\n):\n    \"\"\"Retrieve a specific user by their ID.\"\"\"\n    pass\n\n@app.patch(\n    \"\u002Fusers\u002F{user_id}\",\n    response_model=User,\n    tags=[\"Users\"],\n    summary=\"Update user\",\n    responses={\n        400: {\"model\": ErrorResponse},\n        404: {\"model\": ErrorResponse},\n    },\n)\nasync def update_user(\n    user_id: UUID = Path(..., description=\"User ID\"),\n    user: UserUpdate = ...,\n):\n    \"\"\"Update user attributes.\"\"\"\n    pass\n\n@app.delete(\n    \"\u002Fusers\u002F{user_id}\",\n    status_code=204,\n    tags=[\"Users\", \"Admin\"],\n    summary=\"Delete user\",\n    responses={404: {\"model\": ErrorResponse}},\n)\nasync def delete_user(\n    user_id: UUID = Path(..., description=\"User ID\"),\n):\n    \"\"\"Permanently delete a user.\"\"\"\n    pass\n\n# Export OpenAPI spec\nif __name__ == \"__main__\":\n    import json\n    print(json.dumps(app.openapi(), indent=2))\n```\n\n### Template 3: Code-First (TypeScript\u002FExpress with tsoa)\n\n```typescript\n\u002F\u002F tsoa generates OpenAPI from TypeScript decorators\n\nimport {\n  Controller,\n  Get,\n  Post,\n  Patch,\n  Delete,\n  Route,\n  Path,\n  Query,\n  Body,\n  Response,\n  SuccessResponse,\n  Tags,\n  Security,\n  Example,\n} from \"tsoa\";\n\n\u002F\u002F Models\ninterface User {\n  \u002F** Unique identifier *\u002F\n  id: string;\n  \u002F** User email address *\u002F\n  email: string;\n  \u002F** Display name *\u002F\n  name: string;\n  status: UserStatus;\n  role: UserRole;\n  \u002F** Avatar URL *\u002F\n  avatar?: string;\n  \u002F** Custom metadata *\u002F\n  metadata?: Record\u003Cstring, unknown>;\n  createdAt: Date;\n  updatedAt?: Date;\n}\n\nenum UserStatus {\n  Active = \"active\",\n  Inactive = \"inactive\",\n  Suspended = \"suspended\",\n  Pending = \"pending\",\n}\n\nenum UserRole {\n  User = \"user\",\n  Moderator = \"moderator\",\n  Admin = \"admin\",\n}\n\ninterface CreateUserRequest {\n  email: string;\n  name: string;\n  role?: UserRole;\n  metadata?: Record\u003Cstring, unknown>;\n}\n\ninterface UpdateUserRequest {\n  name?: string;\n  status?: UserStatus;\n  role?: UserRole;\n  metadata?: Record\u003Cstring, unknown>;\n}\n\ninterface Pagination {\n  page: number;\n  limit: number;\n  total: number;\n  totalPages: number;\n  hasNext: boolean;\n  hasPrev: boolean;\n}\n\ninterface UserListResponse {\n  data: User[];\n  pagination: Pagination;\n}\n\ninterface ErrorResponse {\n  code: string;\n  message: string;\n  details?: { field: string; message: string }[];\n  requestId?: string;\n}\n\n@Route(\"users\")\n@Tags(\"Users\")\nexport class UsersController extends Controller {\n  \u002F**\n   * List all users with pagination and filtering\n   * @param page Page number (1-based)\n   * @param limit Items per page (max 100)\n   * @param status Filter by user status\n   * @param search Search by name or email\n   *\u002F\n  @Get()\n  @Security(\"bearerAuth\")\n  @Response\u003CErrorResponse>(400, \"Invalid request\")\n  @Response\u003CErrorResponse>(401, \"Unauthorized\")\n  @Example\u003CUserListResponse>({\n    data: [\n      {\n        id: \"550e8400-e29b-41d4-a716-446655440000\",\n        email: \"john@example.com\",\n        name: \"John Doe\",\n        status: UserStatus.Active,\n        role: UserRole.User,\n        createdAt: new Date(\"2024-01-15T10:30:00Z\"),\n      },\n    ],\n    pagination: {\n      page: 1,\n      limit: 20,\n      total: 1,\n      totalPages: 1,\n      hasNext: false,\n      hasPrev: false,\n    },\n  })\n  public async listUsers(\n    @Query() page: number = 1,\n    @Query() limit: number = 20,\n    @Query() status?: UserStatus,\n    @Query() search?: string,\n  ): Promise\u003CUserListResponse> {\n    \u002F\u002F Implementation\n    throw new Error(\"Not implemented\");\n  }\n\n  \u002F**\n   * Create a new user\n   *\u002F\n  @Post()\n  @Security(\"bearerAuth\")\n  @SuccessResponse(201, \"Created\")\n  @Response\u003CErrorResponse>(400, \"Invalid request\")\n  @Response\u003CErrorResponse>(409, \"Email already exists\")\n  public async createUser(@Body() body: CreateUserRequest): Promise\u003CUser> {\n    this.setStatus(201);\n    throw new Error(\"Not implemented\");\n  }\n\n  \u002F**\n   * Get user by ID\n   * @param userId User ID\n   *\u002F\n  @Get(\"{userId}\")\n  @Security(\"bearerAuth\")\n  @Response\u003CErrorResponse>(404, \"User not found\")\n  public async getUser(@Path() userId: string): Promise\u003CUser> {\n    throw new Error(\"Not implemented\");\n  }\n\n  \u002F**\n   * Update user attributes\n   * @param userId User ID\n   *\u002F\n  @Patch(\"{userId}\")\n  @Security(\"bearerAuth\")\n  @Response\u003CErrorResponse>(400, \"Invalid request\")\n  @Response\u003CErrorResponse>(404, \"User not found\")\n  public async updateUser(\n    @Path() userId: string,\n    @Body() body: UpdateUserRequest,\n  ): Promise\u003CUser> {\n    throw new Error(\"Not implemented\");\n  }\n\n  \u002F**\n   * Delete user\n   * @param userId User ID\n   *\u002F\n  @Delete(\"{userId}\")\n  @Tags(\"Users\", \"Admin\")\n  @Security(\"bearerAuth\")\n  @SuccessResponse(204, \"Deleted\")\n  @Response\u003CErrorResponse>(404, \"User not found\")\n  public async deleteUser(@Path() userId: string): Promise\u003Cvoid> {\n    this.setStatus(204);\n  }\n}\n```\n\n### Template 4: Validation & Linting\n\n```bash\n# Install validation tools\nnpm install -g @stoplight\u002Fspectral-cli\nnpm install -g @redocly\u002Fcli\n\n# Spectral ruleset (.spectral.yaml)\ncat > .spectral.yaml \u003C\u003C 'EOF'\nextends: [\"spectral:oas\", \"spectral:asyncapi\"]\n\nrules:\n  # Enforce operation IDs\n  operation-operationId: error\n\n  # Require descriptions\n  operation-description: warn\n  info-description: error\n\n  # Naming conventions\n  operation-operationId-valid-in-url: true\n\n  # Security\n  operation-security-defined: error\n\n  # Response codes\n  operation-success-response: error\n\n  # Custom rules\n  path-params-snake-case:\n    description: Path parameters should be snake_case\n    severity: warn\n    given: \"$.paths[*].parameters[?(@.in == 'path')].name\"\n    then:\n      function: pattern\n      functionOptions:\n        match: \"^[a-z][a-z0-9_]*$\"\n\n  schema-properties-camelCase:\n    description: Schema properties should be camelCase\n    severity: warn\n    given: \"$.components.schemas[*].properties[*]~\"\n    then:\n      function: casing\n      functionOptions:\n        type: camel\nEOF\n\n# Run Spectral\nspectral lint openapi.yaml\n\n# Redocly config (redocly.yaml)\ncat > redocly.yaml \u003C\u003C 'EOF'\nextends:\n  - recommended\n\nrules:\n  no-invalid-media-type-examples: error\n  no-invalid-schema-examples: error\n  operation-4xx-response: warn\n  request-mime-type:\n    severity: error\n    allowedValues:\n      - application\u002Fjson\n  response-mime-type:\n    severity: error\n    allowedValues:\n      - application\u002Fjson\n      - application\u002Fproblem+json\n\ntheme:\n  openapi:\n    generateCodeSamples:\n      languages:\n        - lang: curl\n        - lang: python\n        - lang: javascript\nEOF\n\n# Run Redocly\nredocly lint openapi.yaml\nredocly bundle openapi.yaml -o bundled.yaml\nredocly preview-docs openapi.yaml\n```\n\n## SDK Generation\n\n```bash\n# OpenAPI Generator\nnpm install -g @openapitools\u002Fopenapi-generator-cli\n\n# Generate TypeScript client\nopenapi-generator-cli generate \\\n  -i openapi.yaml \\\n  -g typescript-fetch \\\n  -o .\u002Fgenerated\u002Ftypescript-client \\\n  --additional-properties=supportsES6=true,npmName=@myorg\u002Fapi-client\n\n# Generate Python client\nopenapi-generator-cli generate \\\n  -i openapi.yaml \\\n  -g python \\\n  -o .\u002Fgenerated\u002Fpython-client \\\n  --additional-properties=packageName=api_client\n\n# Generate Go client\nopenapi-generator-cli generate \\\n  -i openapi.yaml \\\n  -g go \\\n  -o .\u002Fgenerated\u002Fgo-client\n```\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","87afe6ce96220accf50a345dea46784c8c9f210e","YYC3-Plugin-插件协议\u002FYYC3-Plugin-插件协议-plugins-claude\u002Fdocumentation-generation\u002Fskills\u002Fopenapi-spec-generation",0,"https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base","https:\u002F\u002Fkb.yyc3.top\u002F","https:\u002F\u002Fgithub.com\u002FYYC-Cube","万象归元于云枢 | 深栈智启新纪元","2026-11-10 10:37:32",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill openapi-spec-generation",{"tool":39,"command":40},"bunx","bunx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill openapi-spec-generation",{"tool":42,"command":43},"pnpm","pnpm dlx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill openapi-spec-generation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-Plugin-插件协议\u002FYYC3-Plugin-插件协议-plugins-claude\u002Fdocumentation-generation\u002Fskills\u002Fopenapi-spec-generation\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M7CTDWHERCXPQCP0K03A86AS","vercel-sandbox","Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include \"Vercel Sandbox browser\", \"microVM Chrome\", \"agent-browser in sandbox\", \"browser automation on Vercel\", or any task requiring Chrome in a Vercel Sandbox.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fvercel-sandbox\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7CTD8D2BNJY54S65M47HEJA","slack","Interact with Slack workspaces using browser automation. Use when the user needs to check unread channels, navigate Slack, send messages, extract data, find information, search conversations, or automate any Slack task. Triggers include \"check my Slack\", \"what channels have unreads\", \"send a message to\", \"search Slack for\", \"extract from Slack\", \"find who said\", or any task requiring programmatic Slack interaction.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fslack\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7CTCSSB8ZP3Q58C3YZDZK1W","electron","Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include \"automate Slack app\", \"control VS Code\", \"interact with Discord app\", \"test this Electron app\", \"connect to desktop app\", or any task requiring automation of a native Electron application.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Felectron\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7CTCBJY76688V4DCZGWFHGQ","dogfood","Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to \"dogfood\", \"QA\", \"exploratory test\", \"find issues\", \"bug hunt\", \"test this app\u002Fsite\u002Fplatform\", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fdogfood\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7CTC4H0FFGVEAQR9PA4GA1A","agent-browser","Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to \"open a website\", \"fill out a form\", \"click a button\", \"take a screenshot\", \"scrape data from a page\", \"test this web app\", \"login to a site\", \"automate browser actions\", or any task requiring programmatic web interaction.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fagent-browser\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7CTBKVFYBG78FDSABSDJTTQ","shadcn","Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn\u002Fui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for \"shadcn init\", \"create an app with --preset\", \"switch to --preset\", and for building a design system or applying a DESIGN.md or brand spec to shadcn\u002Fui.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-UI-界面组件\u002FYYC3-UI-界面组件-ui\u002Fskills\u002Fshadcn\u002FSKILL.md",[],[]]