OpenAPIConfig¶
OpenAPIConfig is a simple configuration with basic fields for the auto-generated documentation from Esmerald.
Prior to version 2, there were two pieces for the documentation but now it is simplified with a simple one.
Tip
More information about OpenAPI.
You can create your own OpenAPIConfig and populate all the variables needed or you can simply override the settings attributes and allow Esmerald to handle the configuration on its own. It is up to you.
Warning
When passing OpenAPI attributes via instantiation, Esmerald(docs_url='/docs/swagger',...),
those will always be used over the settings or custom configuration.
OpenAPIConfig and application¶
The OpenAPIConfig contains a bunch of simple fields that are needed to serve the documentation
and those can be easily overwritten.
Currently, by default, the URL for the documentation are:
- Swagger -
/docs/swagger. - Redoc -
/docs/redoc. - Stoplight -
/docs/elements. - Rapidoc -
/docs/rapidoc.
Parameters¶
All the parameters and defaults are available in the OpenAPIConfig Reference.
How to use or create an OpenAPIConfig¶
It is very simple actually.
from esmerald import Esmerald, OpenAPIConfig
from esmerald.openapi.models import Contact
openapi_config = OpenAPIConfig(
title="My Application",
docs_url="/mydocs/swagger",
redoc_url="/mydocs/redoc",
stoplight_url="/mydocs/stoplight",
contact=Contact(name="User", email="email@example.com"),
)
app = Esmerald(routes=[...], openapi_config=openapi_config)
This will create your own OpenAPIConfig and pass it to the Esmerald application but what about changing the current
default /docs path?
Let's use an example for clarification.
from esmerald import Esmerald
app = Esmerald(
routes=[...],
docs_url="/another-url/swagger",
redoc_url="/another-url/redoc",
stoplight_url="/another-url/stoplight",
)
From now on the url to access swagger, redoc and stoplight will be:
- Swagger -
/another-url/swagger. - Redoc -
/another-url/redoc. - Stoplight -
/another-url/stoplight.
OpenAPIConfig and the application settings¶
As per normal Esmerald standard of configurations, it is also possible to enable the OpenAPI configurations via settings.
from esmerald import EsmeraldAPISettings, OpenAPIConfig
class AppSettings(EsmeraldAPISettings):
@property
def openapi_config(self) -> OpenAPIConfig:
"""
Override the default openapi_config from Esmerald.
"""
return OpenAPIConfig(
title=self.title,
version=self.version,
contact=self.contact,
description=self.description,
terms_of_service=self.terms_of_service,
license=self.license,
servers=self.servers,
summary=self.summary,
security=self.security,
tags=self.tags,
docs_url=self.docs_url,
redoc_url=self.redoc_url,
swagger_ui_oauth2_redirect_url=self.swagger_ui_oauth2_redirect_url,
redoc_js_url=self.redoc_js_url,
redoc_favicon_url=self.redoc_favicon_url,
swagger_ui_init_oauth=self.swagger_ui_init_oauth,
swagger_ui_parameters=self.swagger_ui_parameters,
swagger_js_url=self.swagger_js_url,
swagger_css_url=self.swagger_css_url,
swagger_favicon_url=self.swagger_favicon_url,
root_path_in_servers=self.root_path_in_servers,
openapi_version=self.openapi_version,
openapi_url=self.openapi_url,
webhooks=self.webhooks,
stoplight_css_url=self.stoplight_css_url,
stoplight_js_url=self.stoplight_js_url,
stoplight_url=self.stoplight_url,
stoplight_favicon_url=self.stoplight_favicon_url,
)
Start the server with your custom settings.
ESMERALD_SETTINGS_MODULE=AppSettings uvicorn src:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.
$env:ESMERALD_SETTINGS_MODULE="AppSettings"; uvicorn src:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.