Skip to content
Skills Library
Programming · Writing

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".

Repository
armory ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

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

generate API docsdocument this APIOpenAPI forFastAPI docsdocument endpointsswagger docs
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

  1. Reference Files
  2. Prerequisites
  3. Workflow
  4. Output Format
  5. Calibration Rules
  6. Error Handling
  7. When NOT to Generate
Original SKILL.md headings · 156 lines, 799 words
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

RepositoryScoreLicence
This page · mathews-tom/armory100MIT
armanzeroeight/fastagent-plugins100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.