OpenAPIConfig¶
OpenAPIConfig is a simple configuration with basic fields for the auto-generated documentation from Ravyn.
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 Ravyn to handle the configuration on its own. It is up to you.
Warning
When passing OpenAPI attributes via instantiation, Ravyn(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 ravyn import Ravyn, OpenAPIConfig
from ravyn.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 = Ravyn(routes=[...], openapi_config=openapi_config)
This will create your own OpenAPIConfig and pass it to the Ravyn application but what about changing the current
default /docs path?
Let's use an example for clarification.
from ravyn import Ravyn
app = Ravyn(
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 Ravyn standard of configurations, it is also possible to enable the OpenAPI configurations via settings.
from ravyn import RavynSettings, OpenAPIConfig
class AppSettings(RavynSettings):
@property
def openapi_config(self) -> OpenAPIConfig:
"""
Override the default openapi_config from Ravyn.
"""
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.
RAVYN_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:RAVYN_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.