api-docs-generator
/api-docs-generator
Audits and enhances FastAPI and REST API documentation: missing descriptions, response codes, examples, docstrings, Pydantic models, OpenAPI spec. Triggers on: "generate API docs", "document this API", "OpenAPI for", "FastAPI docs", "document endpoints", "swagger docs".
- Author
- mathews-tom ↗
- Repository
- armory ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Audits and enhances FastAPI and REST API documentation: missing descriptions, response codes, examples, docstrings, Pydantic models, OpenAPI spec. Triggers on: "generate API docs", "document this API", "OpenAPI for", "FastAPI docs", "document endpoints", "swagger docs".
Triggers from the description
Original author description
Audits and enhances FastAPI and REST API documentation: missing descriptions, response codes, examples, docstrings, Pydantic models, OpenAPI spec. Triggers on: "generate API docs", "document this API", "OpenAPI for", "FastAPI docs", "document endpoints", "swagger docs".
How it works
- Reference Files
- Prerequisites
- Workflow
- Output Format
- Calibration Rules
- Error Handling
- When NOT to Generate
SKILL.md preview
---
name: api-docs-generator
description: 'Audits and enhances FastAPI and REST API documentation: missing descriptions, response codes, examples, docstrings, Pydantic models, OpenAPI spec. Triggers on: "generate API docs", "document this API", "OpenAPI for", "FastAPI docs", "document endpoints", "swagger docs".'
metadata:
version: 1.1.1
category: review
tags: [api, documentation, openapi, fastapi]
difficulty: intermediate
phase: ship
---
# API Docs Generator
Audits API endpoint documentation for completeness, generates enhanced docstrings with
proper parameter descriptions and examples, documents all response codes, and produces
Pydantic model examples — bridging the gap between auto-generated OpenAPI specs and
genuinely useful API documentation.
## Reference Files
| File | Contents | Load When |
| ----------------------------------- | ----------------------------------------------------------------------- | ----------------------------- |
| `references/fastapi-patterns.md` | FastAPI-specific documentation patterns, Path/Query/Body parameter docs | FastAPI endpoint |
| `references/example-generation.md` | Creating realistic field examples, model_config patterns | Example values needed |
| `references/response-codes.md` | Standard HTTP response documentation, error response schemas | Response documentation needed |
| `references/openapi-enhancement.md` | OpenAPI spec enrichment, tag organization, schema documentation | OpenAPI spec review |
## Prerequisites
- Access to the API source code (route definitions, models)
- Framework identification (FastAPI, Flask, Django REST, Express)
## Workflow
### Phase 1: Analyze Endpoints
1. **Inventory endpoints** — List all routes with HTTP method, path, handler function.
2. **Identify models** — Request bodies (Pydantic models, dataclasses), response models,
query parameters, path parameters.
3. **Map dependencies** — Authentication requirements, middleware, shared dependencies.
4. **Read existing docs** — Current docstrings, OpenAPI metadata, inline documentation.
### Phase 2: Audit Documentation
For each endpoint, check:
| Check | What to Verify | Common Gap |
| ---------------------- | ------------------------------------------------ | ------------------------ |
| Endpoint description | Handler has a docstring | Missing or "TODO" |
| Parameter descriptions | Each param has `description=` | Path params undocumented |
| Request example | Body model has `example=` or `json_schema_extra` | No request example |
| Response model | `response_model=` specified | Returns raw dict |
| Error responses | 4xx/5xx documented with `responses=` | Only 200 documented |
| Tags | Endpoint assigned to a tag group | Untagged endpoints |
### Phase 3: Generate Enhancements
1. **Docstrings** — Write clear endpoint descriptions that explain purpose, not
implementation. Include Raises section for documented errors.
2. **Parameter metadata** — Add `description`, `example`, `ge`/`le`/`regex` to
Path, Query, Body parameters.
3. **Model examples** — Add `Field(example=...)` and `model_config` with `json_schema_extra`.
4. **Error responses** — Document every possible error status code with response schema.
5. **Tags** — Group endpoints by resource or feature area.
### Phase 4: Output
Produce a coverage report and enhanced code.
## Output Format
````
## API Documentation Audit
### Coverage Summary
| Metric | Count | Documented | Coverage |
|--------|-------|------------|----------|
| Endpoints | {N} | {M} | {%} |
| Parameters | {N} | {M} | {%} |
| Response codes | {N} | {M} | {%} |
| Models with examples | {N} | {M} | {%} |
### Gaps Identified
| # | Endpoint | Issue | Severity |
|---|----------|-------|----------|
| 1 | `{METHOD} {path}` | {issue} | {High/Medium/Low} |
### Enhanced Code
#### `{METHOD} {path}`
```python
@router.{method}(
"{path}",
response_model={ResponseModel},
summary="{Short summary}",
responses={{
404: {{"description": "{Not found description}"}},
422: {{"description": "Validation error"}},
}},
tags=["{tag}"],
)
async def {handler}(
{param}: {type} = Path(..., description="{description}", example={example}),
) -> {ResponseModel}:
"""
{Full description of what this endpoint does.}
{Additional context about behavior, side effects, or important notes.}
Raises:
404: {Entity} not found
403: Insufficient permissions
"""
````
#### Model: `{ModelName}`
```python
class {ModelName}(BaseModel):
{field}: {type} = Field(..., description="{description}", example={example})
model_config = ConfigDict(
json_schema_extra={{
"example": {{
"{field}": {example_value},
}}
}}
)
```
```text
## Calibration Rules
1. **Describe behavior, not implementation.** "Retrieves the user's profile" is good.
"Calls `db.query(User).filter_by(id=id).first()`" is implementation leakage.
2. **Realistic examples.** `"alice@example.com"` not `"string"`. `42` not `0`.
Examples serve as documentation — they should look like real data.
3. **Document every error code.** If the endpoint can return 404, document it. Users
should never encounter an undocumented error response.
4. **Consistent style.** All endpoints in the same API should use the same documentation
patterns — same tag naming, same description style, same example format.
5. **Don't duplicate the type system.** If the parameter type is `int`, don't write
"An integer" as the description. Write what the integer represents: "Unique user
identifier."
## Error Handling
| Problem | Resolution |
|---------|------------|
| Non-FastAPI framework | Adapt patterns. Document the HTTP contract regardless of framework. |
| No type hints on handlers | Infer types from usage, document uncertainty, suggest adding type hints. |
| Massive API (50+ endpoints) | Prioritize undocumented and public endpoints. Batch output by resource. |
| Generated API (OpenAPI → code) | Document at the spec level, not the generated code level. |
| Authentication varies by endpoint | Document auth requirements per endpoint group. |
## When NOT to Generate
Push back if:
- The API design itself is wrong (bad URL patterns, wrong HTTP methods) — fix the API first
- The user wants SDK generation from OpenAPI — different tool
- The code is a prototype that will change significantly — document after stabilization
```
Files in this package (6)
- SKILL.md 7 KB
- evals/cases.yaml 2 KB
- references/example-generation.md 5 KB
- references/fastapi-patterns.md 5 KB
- references/openapi-enhancement.md 6 KB
- references/response-codes.md 6 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mathews-tom/armory | 100 | MIT |
| armanzeroeight/fastagent-plugins | 100 | MIT |
Database snapshot: 13.11.2026 · package version 466312d911fa (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100python-fastapi-pydantic
Use this skill when building high-performance, asynchronous REST APIs in Python using FastAPI, Pydantic validation, and OpenAPI. - 100api-docs
Write reference documentation or an OpenAPI spec for a REST/HTTP API by reading its source code. Use when the user says "document the API", "write endpoint docs", "generate an OpenAPI/Swagger spec", "what endpoints do we have", or "document this route". - 95api-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. - 100fastapi-expert
Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke to create REST endpoints, define Pydantic models, implement authentication flows, set up async SQLAlchemy database operations, add JWT authentication, build WebSocket endpoints, or generate… - 100fastapi-expert
Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke to create REST endpoints, define Pydantic models, implement authentication flows, set up async SQLAlchemy database operations, add JWT authentication, build WebSocket endpoints, or generate… - 100fastapi-expert
Expert-level FastAPI development for high-performance Python APIs with async support. Use when the user mentions Python, API, async, REST, OpenAPI, or Pydantic, or when the task involves FastAPI Features.