document-api-endpoint

# 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, param...