OpenAPI — Aquilia Documentation
Comprehensive guide and documentation for OpenAPI in the Aquilia framework. View API reference, examples, and implementation patterns.
OpenAPI Generation aquilia.controller.openapi — Production-grade spec extraction from source code Aquilia features a compiler-integrated OpenAPI 3.1.0 engine that extracts schemas, parameter bindings, security schemes, and response shapes directly from your Controller classes and python annotations, serving them via interactive Swagger UI and ReDoc pages. Workspace-Level Integration OpenAPI config is integrated into your application at the workspace level inside your workspace.py: Configuration Note The legacy helper method Integration.openapi(**kwargs) is fully supported as an alternative style. However, importing and configuring OpenAPIIntegration directly is preferred as it enables static type checks and parameter autocomplete in IDEs. OpenAPI Configuration Options OpenAPI generation is enabled by default and configured using the OpenAPIConfig class. You can tune paths, themes, info metadata, and server endpoints. Python to JSON Schema Mapping The generator introspects type hints on routing arguments, request models, and return annotations, casting standard Python types to their JSON Schema equivalents. Python Type Annotation JSON Schema Equivalent '], ['int', ' '], ['float', ' '], ['bool', ' '], ['bytes', ' '], ['None', ' '], ['Union[X, None] / Optional[X]', ' '], ['list[X] / List[X]', ' }'], ['dict[str, X] / Dict[str, X]', ' }'], ['tuple[X, Y]', ' , ], "minItems": 2, "maxItems": 2}'], ['set[X]', ' , "uniqueItems": true}'], ['dataclass / class (with fields)', ' '] ].map(([python, json], i) => ( ))} Spec Inference Strategies To provide complete specifications with minimal boilerplates, the OpenAPIGenerator performs multi-layered static analysis on route handler functions: 1. Parameter Extraction Path variables declared in route patterns (e.g., /users/) are auto-converted to OpenAPI path parameters. Query parameters and headers are inferred from handler metadata annotations and parameters: ") async def get_user(self, id: int, q: str | None = None, x_token: Annotated[str, Header()] = ""): ...`} language="python" highlightLines= /> 2. Request Body Inference For write requests (POST, PUT, PATCH), the generator scans parameters using a 4-tier strategy: Parameter Metadata: Inspects route annotations where the parameter source is explicitly marked as body. Annotated Param: Checks for parameters declared as Annotated[MyContract, Body()]. Docstring Schema: Parses the handler docstring for a JSON example block, e.g. "}. Types are statically inferred from values. Code Introspection: Checks source code lines for calls to await ctx.json() (yielding a generic JSON object body) or await ctx.form() (yielding an urlencoded form body). 3. Response Resolution Success status codes and response schemas are generated based on route metadata: If no response_model is defined, the generator analyzes the handler's python code: Detecting Response.json(...) infers application/json response. Detecting Response.html(...) or template render calls infers text/html response. Detecting Response.text(...) infers text/plain response. Security Schemes Detection If detect_security is enabled, the generator scans the pipeline guards registered on your controllers or routes: Guard Class Name Inferred Security Scheme ))} Swagger UI & ReDoc The generated specification is served at custom paths, rendering responsive documentation playgrounds: Swagger UI ( /docs): Enables developers to inspect schema properties and test endpoints interactively by submitting API requests directly from their browser. In dark mode, it automatically applies color filters to avoid light-flash discomfort. See generate_swagger_html . ReDoc ( /redoc): Provides a beautiful, structured 3-pane layout optimized for reference manuals and large API catalogs. See generate_redoc_html . Manual Spec Generation You can generate the OpenAPI specification dictionary manually from your compiled ControllerRouter : ControllerRouter Configuration Overview )
Go to Homepage