uapi can generate and serve an OpenAPI schema for your API.
from uapi import App app = App() # Register your routes here # Serve the schema at /openapi.json by default app.serve_openapi() # Generate the schema, if you want to access it directly or customize it spec = app.make_openapi_spec()
Additionally, uapi also supports serving several OpenAPI documentation viewers:
app.serve_swaggerui() app.serve_redoc() app.serve_elements()
The documentation viewer will be available at its default URL.
What is referred to as routes in uapi, OpenAPI refers to as operations. This document uses the uapi nomenclature by default.
uapi comes with OpenAPI schema support for the following types:
type: number, format: double)
type: string, format: binary)
type: string, format: date)
type: string, format: date-time)
Operation Summaries and Descriptions#
OpenAPI allows operations to have summaries and descriptions; summaries are usually used as operation labels in OpenAPI tooling.
By default, uapi generates summaries from route names. This can be customized by using your own summary transformer, which is a function taking the actual handler function or coroutine and the route name, and returning the summary string.
app = App() def summary_transformer(handler: Callable, name: str) -> str: """Use the name of the handler function as the summary.""" return handler.__name__ app.serve_openapi(summary_transformer=summary_transformer)
Operation descriptions are generated from handler docstrings by default. This can again be customized by supplying your own description transformer, with the same signature as the summary transformer.
app = App() def desc_transformer(handler: Callable, name: str) -> str: """Use the first line of the docstring as the description.""" doc = getattr(handler, "__doc__", None) if doc is not None: return doc.split("\n") return None app.serve_openapi(description_transformer=desc_transformer)
OpenAPI allows Markdown to be used for descriptions.