Skip to content
Skills Library
Programming · Review & audit

document-api-endpoint

/document-api-endpoint

Use when reconciling an API endpoint''s generated OpenAPI schema and declared response types with its actual runtime response. Not for general API documentation: use docs-and-adrs.

Licence
Apache-2.0
Last repository change
28.09.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
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when reconciling an API endpoint''s generated OpenAPI schema and declared response types with its actual runtime response. Not for general API documentation: use docs-and-adrs.

Original author description

Use when reconciling an API endpoint''s generated OpenAPI schema and declared response types with its actual runtime response. Not for general API documentation: use docs-and-adrs.

How it works

  1. Contract
  2. Inputs
  3. Procedure
  4. Failure and recovery
  5. Output
Original SKILL.md headings · 39 lines, 735 words
SKILL.md preview
---
name: document-api-endpoint
description: 'Use when reconciling an API endpoint''s generated OpenAPI schema and declared response types with its actual runtime response. Not for general API documentation: use docs-and-adrs.'
disable-model-invocation: true
---

# Document and type an API endpoint

## Contract

| Field | Bound contract |
|---|---|
| Trigger | User asks to document, type, or fix OpenAPI schema for an endpoint whose generated spec drifts from its runtime response. |
| Authority | Reversible local: writes only the endpoint class and API documentation files for that one path; rollback is version control (revert to recover). No remote mutation. |
| Side effect | Updates or adds OpenAPI schema annotations and response types for one endpoint path. |
| Done | Endpoint has accurate schema annotations, typed responses matching runtime, and passing local schema validation. |

## Inputs

- The endpoint route and HTTP method(s) to document, plus the serving class or handler (required).
- The runtime response shape: confirmed via a live request, a tool that calls the endpoint, or a test that exercises the path and captures the response (required).
- Optional: a request to promote the endpoint from a private or experimental status to public.

## Procedure

1. Confirm the endpoint's actual runtime response shape. Use a live request, an MCP or test tool that calls the endpoint, or a capturing test. Record the response keys, value types, and nesting. Done when: the serving class and its actual return shape are confirmed.
2. Add or update OpenAPI schema annotations on the endpoint. Apply the framework's schema decorator or annotation mechanism (e.g., `@extend_schema`, `@OpenApiResponse`, `ProducesResponseType`) with operation ID, parameters, response codes, and examples. Reuse the project's existing parameter and example registries where they exist. Done when: the endpoint carries schema annotations with operation ID, parameters, responses, and examples.
3. Reconcile declared response types against the runtime response. Compare every key and type in the declared response type against the confirmed runtime shape. Correct the declared type to match runtime: counts returned as floats instead of integers, IDs declared as one type but emitted as another, nested types with the wrong field count. Reuse the canonical response type instead of re-declaring a copy; use optional-field mixins or partial schemas where the framework supports them. If the payload is proxied from another service and no clean canonical type exists, type it as a broad structure (`dict[str, Any]` or equivalent) and confirm the shape from the owning service. Done when: every declared type matches the runtime response and no duplicate type copies remain.
4. Infer the response type from the producing code where possible. Do not use `cast` or `# type: ignore` to force alignment; refactor the producing code so the type is inferred. Done when: the response type is inferred from producing code with no forced casts or ignores.
5. If a legacy schema definition (a hand-written JSON or YAML file for the path) exists, migrate every method on that path in one change: delete the legacy file and remove its reference from the top-level spec. Most generators do not merge hand-written and decorator-driven methods on the same path, so once any method uses schema annotations, all legacy methods on that path vanish from the generated spec. Done when: every method on the path is migrated and the legacy file and its reference are removed.
6. Validate the generated OpenAPI specification locally. Run the project's schema generation command, the example validation command, the endpoint-specific test, and the lint or pre-commit check on the changed paths. Done when: all validation commands pass.

## Failure and recovery

- Runtime response cannot be obtained: the live request, tool, or test could not confirm the actual response shape. Stop. Report the blocker. Do not guess the response shape or align types against an assumed shape.
- Declared type drifts from runtime: correct the declared type to match runtime or refactor the producing code. Never paper over the drift with `cast` or `# type: ignore`.
- Partial legacy migration: if not every method on a path is migrated in one change, the unmigrated legacy methods vanish from the generated spec. Roll back the path change and migrate all methods together.
- Validation failure: do not claim the done predicate holds. Report the failing check and the offending diff; keep the change uncommitted or revert it.
- Rollback: all changes are VCS-tracked local artifacts; revert the commit or hunks to recover.

## Output

The endpoint with correct schema annotations, typed responses matching runtime, and (when applicable) public status, plus a report naming changed paths, validation results, and any downstream schema regeneration dependency.
Files in this package (2)
  • SKILL.md 5 KB
  • agents/openai.yaml 1 KB

Versions

RepositoryScoreLicence
This page · OutlineDriven/outline-driven-development100Apache-2.0
getsentry/skills100Apache-2.0

Database snapshot: 13.11.2026 · package version af1e87d0fd0c (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

  • 100openapi-inspect
    This skill should be used when the user wants to explore an endpoint, show endpoint details, view endpoint schema, inspect an endpoint, understand what an endpoint accepts, or see endpoint input and output.
  • 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".
  • 95wicked-garden-engineering-api-documentarian
    Specialize in API documentation — OpenAPI specs, endpoint documentation, request/response examples, error documentation, and authentication docs. Use when: API docs, OpenAPI specs, "document this API/endpoint", generating endpoint reference documentation from code, or when the…
  • 100rest-api-design
    Design REST API endpoints with Zod validation and OpenAPI documentation. Use when creating new API routes, validating request/response schemas, or updating API documentation. Activates for endpoint design, schema validation, error handling, and API docs.
  • 100rest-api-design
    Design REST API endpoints with Zod validation and OpenAPI documentation. Use when creating new API routes, validating request/response schemas, or updating API documentation. Activates for endpoint design, schema validation, error handling, and API docs.
  • 100api-docs-writer
    Writes precise, complete reference documentation for HTTP/REST APIs and authors valid OpenAPI 3.1 specifications, including endpoint pages, request/response schemas, parameter tables, authentication, pagination, code samples, and error tables. Use this skill when the user asks…

Feedback and reports

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