# Api Doc Gen

> Generate or update OpenAPI specification from Python/FastAPI route decorators. Validate spec-to-code consistency. Use after adding or changing API endpoints.

- **Type:** Skill
- **Install:** `agentstack add skill-srnichols-plan-forge-api-doc-gen`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [srnichols](https://agentstack.voostack.com/s/srnichols)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [srnichols](https://github.com/srnichols)
- **Source:** https://github.com/srnichols/plan-forge/tree/master/presets/python/.github/skills/api-doc-gen

## Install

```sh
agentstack add skill-srnichols-plan-forge-api-doc-gen
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# API Documentation Generation Skill

## Trigger
"Generate API docs" / "Update OpenAPI spec" / "Document this endpoint"

## Steps

### 1. Discover API Endpoints
```bash
grep -rn "@app\.\(get\|post\|put\|delete\|patch\)" --include="*.py" src/
```
> **If this step fails** (no matches): Try `grep -rn "@router\.\(get\|post\|put\|delete\|patch\)" --include="*.py" src/` for FastAPI APIRouter patterns.

> **If no *.py files found**: Stop and report "No Python project found in this directory."

### 2. Extract Endpoint Details
For each endpoint, document:
- HTTP method and path (from `@app.get("/path")` decorators)
- Request body schema (from Pydantic model type hints)
- Query parameters (from `Query()` parameter defaults)
- Path parameters (from `{param}` in route paths)
- Response schema (from `response_model` decorator argument)
- Authentication requirements (from `Depends()` security dependencies)

### 3. Generate/Update OpenAPI Spec
FastAPI generates OpenAPI automatically. Verify the generated spec:
```bash
# Start the app and fetch the auto-generated spec
python -c "from main import app; import json; print(json.dumps(app.openapi(), indent=2))"
```
> **If this step fails**: Check that the app entry point is correct — try `from app.main import app` or inspect `pyproject.toml` for the entry point.

```yaml
openapi: 3.1.0
info:
  title: (project name from pyproject.toml)
  version: (from pyproject.toml or VERSION file)
paths:
  /api/v1/resource:
    get:
      summary: Brief description
      parameters: [...]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
```

### 4. Validate Consistency
Use the `forge_analyze` MCP tool to verify spec-to-code consistency:
- [ ] Every route decorator has a matching spec entry
- [ ] No spec entries without corresponding code (ghost endpoints)
- [ ] Request/response schemas match actual Pydantic models
- [ ] Status codes match `HTTPException` raises and `status_code` parameters
- [ ] Auth requirements match `Depends()` security chains

### 5. Report
```
API Documentation Status:
  Endpoints in code:    N
  Endpoints in spec:    N
  Missing from spec:    N (list them)
  Ghost entries:        N (in spec but not in code)
  Schema mismatches:    N

Overall: PASS / FAIL
```

## Safety Rules
- NEVER invent endpoints not in the code
- ALWAYS preserve existing spec customizations (descriptions, examples)
- Validate against actual route decorators, not assumptions
- Flag breaking changes (removed endpoints, changed schemas)
- Run `pytest` after any spec-related code changes

## Temper Guards

| Shortcut | Why It Breaks |
|----------|--------------|
| "The code is self-documenting" | Code shows implementation, not intent. API consumers need contracts, not source code. |
| "We'll add the OpenAPI spec later" | Specs drift from implementation immediately. Generate alongside code or they'll never match. |
| "Only internal consumers, no docs needed" | Internal APIs become external APIs. Undocumented internal APIs create onboarding bottlenecks. |
| "Examples aren't necessary" | Examples are the most-read section of any API doc. Abstract schemas don't show real usage. |

## Warning Signs

- Endpoints without response type annotations — returns untyped or generic responses
- Spec doesn't match actual routes — OpenAPI spec has different paths/methods than the running API
- No request/response examples — spec has schemas but no concrete usage examples
- Error responses undocumented — only success codes documented, error payloads missing
- Spec not validated against running API — generated once but never verified against live routes

## Exit Proof

After completing this skill, confirm:
- [ ] OpenAPI spec generated or updated (FastAPI auto-gen / flask-smorest)
- [ ] Spec validates against actual endpoints — no ghost entries, no missing routes
- [ ] Request/response examples present for key routes
- [ ] Error responses documented (4xx/5xx with schemas)
- [ ] `pip install -e .` succeeds after any spec-related code changes
## Persistent Memory (if OpenBrain is configured)

- **Before generating docs**: `search_thoughts("API design", project: "", created_by: "copilot-vscode", type: "convention")` — load API naming conventions, pagination patterns, and error response standards
- **After spec update**: `capture_thought("API doc: ", project: "", created_by: "copilot-vscode", source: "skill-api-doc-gen")` — persist API evolution for breaking change tracking

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [srnichols](https://github.com/srnichols)
- **Source:** [srnichols/plan-forge](https://github.com/srnichols/plan-forge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-srnichols-plan-forge-api-doc-gen
- Seller: https://agentstack.voostack.com/s/srnichols
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.