Vishesh 'ironeagle' Bangotra
72b5be6976
- Restrict mkdocstrings generation to real Python packages (require __init__.py) - Add explicit documentation section for CLI scaffolding and templates - Generalize CLI to support multiple templates with dynamic discovery - Package templates correctly for importlib.resources access - Add fully documented health_app template (app entry point and handlers) - Fix setuptools package-data configuration for bundled templates These changes make documentation import-safe, clarify package boundaries, and provide a deterministic, OpenAPI-first scaffolding workflow via CLI.
66 lines
2.1 KiB
Python
66 lines
2.1 KiB
Python
"""
|
|
OpenAPI-first FastAPI application template.
|
|
|
|
This package contains a minimal, fully working example of an
|
|
OpenAPI-first FastAPI service built using the ``openapi_first`` library.
|
|
|
|
The application is assembled exclusively from:
|
|
- an OpenAPI specification (``openapi.yaml``)
|
|
- a handler namespace (``routes``)
|
|
|
|
No routing decorators, implicit behavior, or framework-specific
|
|
convenience abstractions are used. All HTTP routes, methods, and
|
|
operation bindings are defined in OpenAPI and enforced at application
|
|
startup.
|
|
|
|
This package is intended to be copied as a starting point for new
|
|
services via the ``openapi-first`` CLI. It is not part of the
|
|
``openapi_first`` library API surface.
|
|
|
|
----------------------------------------------------------------------
|
|
Scaffolding via CLI
|
|
----------------------------------------------------------------------
|
|
|
|
Create a new OpenAPI-first health check service using the bundled
|
|
template:
|
|
|
|
openapi-first health_app
|
|
|
|
Create the service in a custom directory:
|
|
|
|
openapi-first health_app my-health-service
|
|
|
|
List all available application templates:
|
|
|
|
openapi-first --list
|
|
|
|
The CLI copies template files verbatim into the target directory.
|
|
No code is generated or modified beyond the copied scaffold.
|
|
|
|
----------------------------------------------------------------------
|
|
Client Usage Example
|
|
----------------------------------------------------------------------
|
|
|
|
The same OpenAPI specification used by the server can be used to
|
|
construct a strict, operationId-driven HTTP client.
|
|
|
|
Example client call for the ``get_health`` operation:
|
|
|
|
from openapi_first.loader import load_openapi
|
|
from openapi_first.client import OpenAPIClient
|
|
|
|
spec = load_openapi("openapi.yaml")
|
|
client = OpenAPIClient(spec)
|
|
|
|
response = client.get_health()
|
|
|
|
assert response.status_code == 200
|
|
assert response.json() == {"status": "ok"}
|
|
|
|
Client guarantees:
|
|
- One callable per OpenAPI ``operationId``
|
|
- No hardcoded URLs or HTTP methods in user code
|
|
- Path and request parameters must match the OpenAPI specification
|
|
- Invalid or incomplete OpenAPI specs fail at client construction time
|
|
"""
|