Visualizing Contracts in Swagger UI¶
Assuming you include contracts in OpenAPI schema (see Documenting Contracts in OpenAPI),
they will be available per each path as a x-contracts
extension field.
Unfortunately, Swagger UI does not pretty-prints extension fields, so that the contracts
end up barely readable as a long single-line string.
While you might inspect the OpenAPI specification, it is much more convenient to read contracts in a nice structured layout. To that end, we developed swagger-ui-plugin-contracts, a JavaScript plugin that can be readily included in Swagger UI.
There are a couple of options how you can include the plugin in the Swagger UI of your
app
.
Use set_up_route_for_docs_with_contracts_plugin
¶
The most straightforward way is to replace the documentation route (i.e., the route corresponding to Swagger UI) is rendered.
First, you need to explicitly tell your app
to skip creating the documentation route
at setup by setting docs_url=None
:
app = FastAPI(docs_url=None)
Fastapi-icontracts gives you the function
set_up_route_for_docs_with_contracts_plugin()
which
creates the documentation route with the contracts plugin included.
You need to call it explicitly once the app
has been set up
(see the full example):
fastapi_icontract.set_up_route_for_docs_with_contracts_plugin(
app=app, path="/docs")
From then on, Swagger UI with swagger-ui-plugin-contracts will be available at
"/docs"
path.
Specify Your Own Documentation Endpoint¶
fastapi_icontract.set_up_route_for_docs_with_contracts_plugin()
does not
really provide a way to customize the documentation endpoint.
For example, it does not allow you to specify a different URL from where swagger-ui-plugin-contracts should be fetched, or add additional plugins. If you need such more involved customizations, you need to specify the documentation endpoint yourself.
If you only need to change the URLs of the relevant files (e.g., to Swagger UI,
swagger-ui-plugin-contracts, etc.), you can use the function
fastapi_icontract.swagger_ui.get_swagger_ui_html()
:
If you need to include additional Swagger UI plugins or customize otherwise
the HTML code of the documentation, you need to re-write your own version
of fastapi_icontract.swagger_ui.get_swagger_ui_html()
.