generate-openapi

Generate OpenAPI Specification

Generate OpenAPI 3.0 spec from API code or create from scratch.

Context

• Current directory: !pwd
• API files: !find . -name "*route*" -o -name "*controller*" -o -name "*api*" 2>/dev/null | grep -v node_modules | head -10

Your Task

Generate a comprehensive OpenAPI 3.0 specification for the API.

Arguments

• $1: Source file or directory (optional) - Path to API code to analyze

Steps

1. Analyze existing API code (if provided):

   • Read route definitions
   • Identify endpoints and HTTP methods
   • Extract request/response schemas
   • Find authentication patterns

2. Create OpenAPI spec structure:

   openapi: 3.0.0
   info:
     title: API Name
     version: 1.0.0
     description: API description
   
   servers:
     - url: https://api.example.com/v1
       description: Production
   
   paths: {}
   
   components:
     schemas: {}
     responses: {}
     parameters: {}
     securitySchemes: {}
   

3. Define paths from routes:

   For each endpoint found:

   paths:
     /users:
       get:
         summary: List users
         tags:
           - Users
         parameters:
           - name: page
             in: query
             schema:
               type: integer
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   type: object
                   properties:
                     data:
                       type: array
                       items:
                         $ref: '#/components/schemas/User'
       
       post:
         summary: Create user
         requestBody:
           required: true
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/CreateUserRequest'
         responses:
           '201':
             description: User created
   

4. Define schemas: