Skip to content

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.

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",
    redoc_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.