API Documentation Generator

Generate OpenAPI/Swagger specifications and API documentation from code or design. Use when creating API docs, generating OpenAPI specs, or documenting REST APIs.

armanzeroeight Updated Sep 10, 2026

Install

Press C to copy

$ npx skillmds@latest add armanzeroeight/api-documentation-generator

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

Download SKILL.md

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/armanzeroeight/api-documentation-generator.svg)](https://skillmd.com/skills/armanzeroeight/api-documentation-generator)

Trust & safety

Audits pending

Not yet audited · commit ad0c545

Permissions this skill uses

Makes network calls
The instructions fetch remote URLs or call external services.
Reads secrets
The instructions read tokens, keys, or other credentials.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

API Documentation Generator

Generate OpenAPI/Swagger specifications and comprehensive API documentation.

Quick Start

Create OpenAPI 3.0 specs with paths, schemas, and examples for complete API documentation.

Instructions

OpenAPI 3.0 Structure

Basic structure:

openapi: 3.0.0
info:
  title: API Name
  version: 1.0.0
  description: API description
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Info Section

info:
  title: E-commerce API
  version: 1.0.0
  description: |
    REST API for e-commerce platform.
    
    ## Authentication
    Use Bearer token in Authorization header.
    
    ## Rate Limiting
    1000 requests per hour per API key.
  contact:
    name: API Support
    email: api@example.com
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

Servers

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
  - url: http://localhost:3000/v1
    description: Development

Paths and Operations

GET endpoint:

paths:
  /users:
    get:
      summary: List users
      description: Retrieve a paginated list of users
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'

POST endpoint:

  /users:
    post:
      summary: Create user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            example:
              name: John Doe
              email: john@example.com
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'

Path parameters:

  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: User ID
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

Components - Schemas

Simple schema:

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: John Doe
        email:
          type: string
          format: email
          example: john@example.com
        created_at:
          type: string
          format: date-time

Nested schema:

    Order:
      type: object
      properties:
        id:
          type: integer
        customer:
          $ref: '#/components/schemas/User'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        total:
          type: number
          format: float

Enum:

    OrderStatus:
      type: string
      enum:
        - pending
        - processing
        - shipped
        - delivered
        - cancelled

OneOf (union types):

    Payment:
      oneOf:
        - $ref: '#/components/schemas/CreditCardPayment'
        - $ref: '#/components/schemas/PayPalPayment'
      discriminator:
        propertyName: payment_type

Components - Responses

Reusable responses:

components:
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
    
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Components - Parameters

Reusable parameters:

components:
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
    
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        maximum: 100
    
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: integer

Security Schemes

Bearer token:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

API Key:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

OAuth 2.0:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Read access
            write: Write access

Examples

Multiple examples:

responses:
  '200':
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
        examples:
          admin:
            summary: Admin user
            value:
              id: 1
              name: Admin
              role: admin
          regular:
            summary: Regular user
            value:
              id: 2
              name: John
              role: user

Tags

Organize endpoints:

tags:
  - name: Users
    description: User management
  - name: Products
    description: Product catalog
  - name: Orders
    description: Order processing

paths:
  /users:
    get:
      tags:
        - Users

Complete Example

openapi: 3.0.0
info:
  title: Blog API
  version: 1.0.0
  description: RESTful API for blog platform

servers:
  - url: https://api.blog.com/v1

paths:
  /posts:
    get:
      summary: List posts
      tags:
        - Posts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Post'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
    
    post:
      summary: Create post
      tags:
        - Posts
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - content
              properties:
                title:
                  type: string
                content:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Post created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'

  /posts/{id}:
    get:
      summary: Get post
      tags:
        - Posts
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    Post:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        content:
          type: string
        author:
          $ref: '#/components/schemas/User'
        created_at:
          type: string
          format: date-time
    
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
    
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
    
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
    
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
  
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

Generating from Code

From Express.js

// Use swagger-jsdoc
/**
 * @swagger
 * /users:
 *   get:
 *     summary: List users
 *     responses:
 *       200:
 *         description: Success
 */
app.get('/users', (req, res) => {
  // Handler
});

From FastAPI (Python)

# FastAPI auto-generates OpenAPI
@app.get("/users", response_model=List[User])
async def list_users():
    return users

From ASP.NET Core

// Use Swashbuckle
[HttpGet]
[ProducesResponseType(typeof(List<User>), 200)]
public IActionResult GetUsers()
{
    return Ok(users);
}

Tools

Swagger Editor: https://editor.swagger.io Swagger UI: Interactive documentation Redoc: Alternative documentation UI Postman: Import OpenAPI for testing

Best Practices

Use $ref for reusability:

Define schemas once
Reference in multiple places
Easier maintenance

Include examples:

Help developers understand
Enable better testing
Show expected formats

Document errors:

All possible status codes
Error response format
Error codes and meanings

Version your API:

Include version in URL or header
Document breaking changes
Maintain old versions

Keep it updated:

Generate from code when possible
Review regularly
Update with API changes

---name: api-documentation-generatordescription: Generate OpenAPI/Swagger specifications and API documentation from code or design. Use when creating API docs, generating OpenAPI specs, or documenting REST APIs.---# API Documentation GeneratorGenerate OpenAPI/Swagger specifications and comprehensive API documentation.## Quick StartCreate OpenAPI 3.0 specs with paths, schemas, and examples for complete API documentation.## Instructions### OpenAPI 3.0 Structure**Basic structure:**```yamlopenapi: 3.0.0info: title: API Name version: 1.0.0 description: API descriptionservers: - url: https://api.example.com/v1paths: /users: get: summary: List users responses: '200': description: Successcomponents: schemas: User: type: object properties: id: type: integer name: type: string```### Info Section```yamlinfo: title: E-commerce API version: 1.0.0 description: | REST API for e-commerce platform. ## Authentication Use Bearer token in Authorization header. ## Rate Limiting 1000 requests per hour per API key. contact: name: API Support email: api@example.com url: https://example.com/support license: name: MIT url: https://opensource.org/licenses/MIT```### Servers```yamlservers: - url: https://api.example.com/v1 description: Production - url: https://staging-api.example.com/v1 description: Staging - url: http://localhost:3000/v1 description: Development```### Paths and Operations**GET endpoint:**```yamlpaths: /users: get: summary: List users description: Retrieve a paginated list of users tags: - Users parameters: - name: page in: query schema: type: integer default: 1 - name: per_page in: query schema: type: integer default: 20 responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/User' meta: $ref: '#/components/schemas/PaginationMeta'```**POST endpoint:**```yaml /users: post: summary: Create user tags: - Users requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' example: name: John Doe email: john@example.com responses: '201': description: User created content: application/json: schema: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/BadRequest'```**Path parameters:**```yaml /users/{id}: get: summary: Get user by ID parameters: - name: id in: path required: true schema: type: integer description: User ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/User' '404': $ref: '#/components/responses/NotFound'```### Components - Schemas**Simple schema:**```yamlcomponents: schemas: User: type: object required: - id - email properties: id: type: integer example: 1 name: type: string example: John Doe email: type: string format: email example: john@example.com created_at: type: string format: date-time```**Nested schema:**```yaml Order: type: object properties: id: type: integer customer: $ref: '#/components/schemas/User' items: type: array items: $ref: '#/components/schemas/OrderItem' total: type: number format: float```**Enum:**```yaml OrderStatus: type: string enum: - pending - processing - shipped - delivered - cancelled```**OneOf (union types):**```yaml Payment: oneOf: - $ref: '#/components/schemas/CreditCardPayment' - $ref: '#/components/schemas/PayPalPayment' discriminator: propertyName: payment_type```### Components - Responses**Reusable responses:**```yamlcomponents: responses: NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ValidationError' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error'```### Components - Parameters**Reusable parameters:**```yamlcomponents: parameters: PageParam: name: page in: query schema: type: integer default: 1 LimitParam: name: limit in: query schema: type: integer default: 20 maximum: 100 IdParam: name: id in: path required: true schema: type: integer```### Security Schemes**Bearer token:**```yamlcomponents: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWTsecurity: - BearerAuth: []```**API Key:**```yamlcomponents: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key```**OAuth 2.0:**```yamlcomponents: securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read: Read access write: Write access```### Examples**Multiple examples:**```yamlresponses: '200': content: application/json: schema: $ref: '#/components/schemas/User' examples: admin: summary: Admin user value: id: 1 name: Admin role: admin regular: summary: Regular user value: id: 2 name: John role: user```### Tags**Organize endpoints:**```yamltags: - name: Users description: User management - name: Products description: Product catalog - name: Orders description: Order processingpaths: /users: get: tags: - Users```## Complete Example```yamlopenapi: 3.0.0info: title: Blog API version: 1.0.0 description: RESTful API for blog platformservers: - url: https://api.blog.com/v1paths: /posts: get: summary: List posts tags: - Posts parameters: - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' responses: '200': description: Success content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Post' meta: $ref: '#/components/schemas/PaginationMeta' post: summary: Create post tags: - Posts security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - title - content properties: title: type: string content: type: string tags: type: array items: type: string responses: '201': description: Post created content: application/json: schema: $ref: '#/components/schemas/Post' /posts/{id}: get: summary: Get post tags: - Posts parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Post' '404': $ref: '#/components/responses/NotFound'components: schemas: Post: type: object properties: id: type: integer title: type: string content: type: string author: $ref: '#/components/schemas/User' created_at: type: string format: date-time User: type: object properties: id: type: integer name: type: string email: type: string PaginationMeta: type: object properties: total: type: integer page: type: integer per_page: type: integer Error: type: object properties: error: type: object properties: code: type: string message: type: string parameters: PageParam: name: page in: query schema: type: integer default: 1 LimitParam: name: limit in: query schema: type: integer default: 20 responses: NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWTsecurity: - BearerAuth: []```## Generating from Code### From Express.js```javascript// Use swagger-jsdoc/** * @swagger * /users: * get: * summary: List users * responses: * 200: * description: Success */app.get('/users', (req, res) => { // Handler});```### From FastAPI (Python)```python# FastAPI auto-generates OpenAPI@app.get("/users", response_model=List[User])async def list_users(): return users```### From ASP.NET Core```csharp// Use Swashbuckle[HttpGet][ProducesResponseType(typeof(List<User>), 200)]public IActionResult GetUsers(){ return Ok(users);}```## Tools**Swagger Editor**: https://editor.swagger.io**Swagger UI**: Interactive documentation**Redoc**: Alternative documentation UI**Postman**: Import OpenAPI for testing## Best Practices**Use $ref for reusability:**- Define schemas once- Reference in multiple places- Easier maintenance**Include examples:**- Help developers understand- Enable better testing- Show expected formats**Document errors:**- All possible status codes- Error response format- Error codes and meanings**Version your API:**- Include version in URL or header- Document breaking changes- Maintain old versions**Keep it updated:**- Generate from code when possible- Review regularly- Update with API changes

armanzeroeight/fastagent-plugins/tree/main/plugins/api-toolkit/skills/api-documentation-generator commit ad0c54547d

Frequently asked questions

npx skillmds@latest add armanzeroeight/api-documentation-generator