OpenAPIConfig¶
OpenAPIConfig — это простая конфигурация с основными полями для автогенерируемой документации в Esmerald.
До версии 2 для документации требовались две отдельные настройки, но теперь они объединены в одну, упрощенную конфигурацию.
Tip
Больше информации о OpenAPI.
Вы можете создать OpenAPIConfig и заполнить все необходимые переменные или просто
переопределить атрибуты настроек.
Выбор за вами.
Warning
При передаче атрибутов OpenAPI через создание экземпляра, например, Esmerald(docs_url='/docs/swagger',...),
эти параметры всегда будут использоваться вместо настроек или пользовательской конфигурации.
OpenAPIConfig и приложение¶
OpenAPIConfig содержит набор простых полей, необходимых для отображения документации,
которые можно легко переопределить.
На данный момент, по умолчанию, URL для документации следующие:
- Swagger -
/docs/swagger. - Redoc -
/docs/redoc. - Stoplight -
/docs/elements. - Rapidoc -
/docs/rapidoc.
Параметры¶
Все параметры и значения по умолчанию доступны в справочнике OpenAPIConfig.
Как использовать или создать OpenAPIConfig¶
На самом деле это очень просто.
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)
Это создаст ваш собственный OpenAPIConfig и передаст его приложению Esmerald, но как насчет
изменения текущего пути по умолчанию /docs?
Давайте рассмотрим пример.
from esmerald import Esmerald
app = Esmerald(
routes=[...],
docs_url="/another-url/swagger",
redoc_url="/another-url/redoc",
stoplight_url="/another-url/stoplight",
)
Теперь URL для доступа к swagger, redoc и stoplight будет следующим:
- Swagger -
/another-url/swagger. - Redoc -
/another-url/redoc. - Stoplight -
/another-url/stoplight.
OpenAPIConfig и настройки приложения¶
В соответствии со стандартом конфигурации Esmerald, также можно включить конфигурацию OpenAPI через настройки.
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,
)
Запуск сервера с пользовательскими настройками.
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.