OpenAPI

Execution Workflow

1. Decide whether OpenAPI should be enabled, restricted, or disabled for the app.
2. Set app-level OpenAPIConfig for title, version, docs endpoints, servers, tags, and render plugins.
3. Add route-level metadata deliberately: summary, description, response_description, tags, security, operation_id, raises, and include_in_schema.
4. Use schema-generation customization only when default model generation is insufficient.
5. Choose UI render plugins and endpoint paths intentionally for each environment.
6. Validate that generated docs match real request, auth, and metrics behavior.

Core Rules

• Keep documentation truthful to runtime behavior.
• Centralize OpenAPI config at app construction.
• Use route-level metadata only where it improves clarity or correctness.
• Disable schema generation with openapi_config=None only when docs must not be exposed.
• Keep request, response, security, and metrics documentation aligned with the skills that own those runtime behaviors.
• Prefer current render-plugin configuration over legacy controller-style customization paths.