No project description provided
Project description
openapi-bridge
OpenAPI endpoint decorator with pydantic (>=2.0.0) integration.
Allows for almost seamless integration of pydantic models with OpenAPI, generating YAML for the endpoint from type hints.
Using the @endpoint
decorator
Example:
@endpoint("/foo/{foo_id}")
def foo(*, foo_id: int, debug: Optional[bool] = False) -> pydantic_models.Foo:
"""
Foo summary.
Lengthy foo description.
@param foo_id The Foo ID in the database.
@param debug Set to True to include debug information.
"""
result = _do_something(id, debug)
return pydantic_models.Foo(**result)
As you can see from the example, the decorator takes a path (which may include
a path parameter, in this case id
). You can also give it an HTTP method, a
path prefix (e.g. to distinguish between internal and external API functions),
and security directives.
Information about the endpoint is gathered from both the type annotations of the decorated function and its docstring.
(!) Every parameter (except the optional user
) must be keyword-only, have a
type hint and a @param help text in the docstring. Un-annotated or undocumented
parameters are considered to be a hard error and will raise an exception on
startup.
Normally you can just return an instance of the annotated type, and the
decorator will handle it correctly, adding an HTTP status 200. If you need to
return something else, e.g. some redirect or a 204 ("no content"), you can to
return a (raw_content, http_status)
tuple instead, e.g.:
return None, 204
The docstring of an endpoint contains its summary, description, the section the documentation is listed under, and parameter help, as well as (optionally) its response in various circumstances.
The summary is the first paragraph of the docstring; the description is taken to be any further paragraphs until the first @keyword.
We recognize the following keywords to designate parts of the documentation:
@section <section name>
: endpoint is listed in this section.@param <param name> <help text>
: explanation of the given parameter.@example <param name> <example text>
: example values of the parameter.@response <http status> <JSON>
: allows for non-standard responses.
YAML Generation
If you're building a Connexion app, you can use the collected endpoints in your
create_app()
function:
def create_app():
# TODO: import all modules with @endpoints here!!
api_specs = {
"paths": openapi_bridge.PATHS["default"],
**openapi_bridge.get_pydantic_schemata(pydantic_models),
}
connexion_app.add_api(api_specs)
(!) You need to import all the modules with endpoints here in order to register them. This is easy to forget! If you test a new endpoint and only ever get 404, you might have forgotten to import that module ;-)
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for openapi_bridge-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bb7b018137c5d606824af112064d0e0ce81aeda83ab2df094a58fa86c0c68688 |
|
MD5 | 6850c49dfad76f224c316de3ba016c70 |
|
BLAKE2b-256 | 392dcc37e322a125be9063f6dc1c618b72471ecb3a46ee775d15432eeb876ee2 |