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

api-documentation-generator

Safety Notice

Copy this and send it to your AI assistant to learn

FastAPI auto-generates OpenAPI

Source Transparency

Related Skills

gcp-cost-optimizer

schema-designer

terraform-state-manager

aws-cost-optimizer