# API Docs

> Generate OpenAPI 3.1 specs and documentation from code. Supports Express, FastAPI, Flask, NestJS, Spring Boot, Gin, Rails, and more. Use when documenting APIs, creating OpenAPI specs, or generating API reference docs.

- Skill: `iamvirul/api-docs` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add iamvirul/api-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iamvirul/api-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: iamvirul (https://skillmd.com/u/iamvirul)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iamvirul/api-docs

---


# API Documentation Generator

Generate production-ready OpenAPI 3.1 specifications and documentation from your codebase.

## Workflow

### Phase 1: Discovery

1. **Detect framework** by scanning for:
   - `package.json` → Express, NestJS, Fastify, Hono
   - `requirements.txt` / `pyproject.toml` → FastAPI, Flask, Django REST
   - `go.mod` → Gin, Echo, Chi, Fiber
   - `Gemfile` → Rails API
   - `pom.xml` / `build.gradle` → Spring Boot
   - `Cargo.toml` → Axum, Actix-web

2. **Find API entry points**:
   ```
   # Common patterns to search
   app.get|post|put|patch|delete  # Express/Fastify
   @app.route|@router             # Flask/FastAPI
   @GetMapping|@PostMapping       # Spring
   router.GET|POST                # Gin/Echo
   resources|get|post             # Rails
   @Controller|@Get|@Post         # NestJS
   ```

3. **Extract endpoint metadata**:
   - HTTP method and path
   - Path parameters (`:id`, `{id}`, `<id>`)
   - Query parameters
   - Request body schema
   - Response schemas and status codes
   - Authentication requirements
   - Middleware/decorators

### Phase 2: Schema Extraction

1. **Type definitions** → OpenAPI components/schemas:
   - TypeScript interfaces/types
   - Python Pydantic models, dataclasses, TypedDict
   - Go structs with json tags
   - Java/Kotlin DTOs
   - Ruby serializers

2. **Validation rules** → OpenAPI constraints:
   - Required fields
   - Min/max values
   - String patterns (email, uuid, etc.)
   - Enums
   - Array constraints

3. **Existing documentation**:
   - JSDoc/TSDoc comments
   - Python docstrings
   - Go doc comments
   - Swagger/OpenAPI annotations
   - README files

### Phase 3: OpenAPI Generation

Generate `openapi.yaml` with:

```yaml
openapi: 3.1.0
info:
  title: <extracted from package.json/pyproject.toml or ask>
  version: <from version file or git tag>
  description: <from README or generate>
servers:
  - url: <detect from env/config or use placeholder>
paths:
  /endpoint:
    get:
      summary: <from docstring or generate>
      description: <detailed description>
      operationId: <function name>
      tags: [<from route grouping>]
      parameters: [<extracted>]
      requestBody: <if applicable>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseType'
              example: <generate realistic example>
        '400': <validation errors>
        '401': <if auth required>
        '404': <if path params>
        '500': <server error>
      security: [<detected auth>]
components:
  schemas: <all extracted types>
  securitySchemes: <detected auth methods>
```

### Phase 4: Documentation Output

Based on `$ARGUMENTS` or default to all:

1. **OpenAPI Spec** (`openapi.yaml`):
   - Valid OpenAPI 3.1
   - Realistic examples for all schemas
   - Comprehensive error responses

2. **Markdown** (`API.md`):
   - Table of contents
   - Authentication section
   - Endpoint reference with examples
   - Schema definitions
   - Error codes

3. **Postman Collection** (`postman.json`):
   - Importable collection
   - Environment variables
   - Pre-configured requests

### Phase 5: Validation

Before finalizing, validate:

1. **Spec validity**:
   ```bash
   npx @redocly/cli lint openapi.yaml
   ```
   Or if not available, validate structure manually.

2. **Coverage check**: List any endpoints found but not documented

3. **Quality checks**:
   - All endpoints have descriptions
   - All parameters documented
   - Response examples provided
   - Auth requirements specified

## Framework-Specific Patterns

See [reference.md](reference.md) for detailed extraction patterns per framework.

## Output Format Selection

| Argument | Output |
|----------|--------|
| `openapi` | OpenAPI 3.1 YAML only |
| `markdown` | API.md documentation |
| `postman` | Postman collection JSON |
| `all` (default) | All formats |
| `html` | Redoc-ready HTML |

## Example Usage

```
/api-docs                    # Auto-detect, generate all formats
/api-docs fastapi openapi    # FastAPI project, OpenAPI only
/api-docs express markdown   # Express project, Markdown only
```

## Quality Standards

Generated documentation MUST include:
- [ ] All public endpoints documented
- [ ] Request/response examples for each endpoint
- [ ] Authentication requirements clearly stated
- [ ] Error responses documented (4xx, 5xx)
- [ ] Parameter constraints (required, types, validation)
- [ ] Consistent naming and formatting