Skip to content

OpenAPIConfig class

Reference for the OpenAPIConfig class object and how to use it.

Read more about how to use the OpenAPIConfig in your application and leverage the system.

How to import

from esmerald import OpenAPIConfig

esmerald.config.openapi.OpenAPIConfig

Bases: BaseModel

An instance of OpenAPIConfig.

This object is then used by Esmerald to create the OpenAPI documentation.

Note: Here is where the defaults for Esmerald OpenAPI are overriden and if this object is passed, then the previous defaults of the settings are ignored.

Tip

This is the way you could override the defaults all in one go instead of doing attribute by attribute.

Example

from esmerald import OpenAPIConfig

openapi_config = OpenAPIConfig(
    title="Black Window",
    openapi_url="/openapi.json",
    docs_url="/docs/swagger",
    redoc_url="/docs/redoc",
)

app = Esmerald(openapi_config=openapi_config)

Important

Esmerald when starting an application, checks the attributes and looks for an openapi_config parameter.

If the parameter is not specified, Esmerald will automatically use the internal settings system to generate the default OpenAPIConfig and populate the values.

title class-attribute instance-attribute

title = None

Title of the application/API documentation.

version class-attribute instance-attribute

version = None

The version of the API documentation.

summary class-attribute instance-attribute

summary = None

Simple and short summary text of the application/API.

description class-attribute instance-attribute

description = None

A longer and more descriptive explanation of the application/API documentation.

contact class-attribute instance-attribute

contact = None

API contact information. This is an OpenAPI schema contact, meaning, in a dictionary format compatible with OpenAPI or an instance of esmerald.openapi.schemas.v3_1_0.contact.Contact.

terms_of_service class-attribute instance-attribute

terms_of_service = None

URL to a page that contains terms of service.

license class-attribute instance-attribute

license = None

API Licensing information. This is an OpenAPI schema licence, meaning, in a dictionary format compatible with OpenAPI or an instance of esmerald.openapi.schemas.v3_1_0.license.License.

security class-attribute instance-attribute

security = None

API Security requirements information. This is an OpenAPI schema security, meaning, in a dictionary format compatible with OpenAPI or an instance of esmerald.openapi.schemas.v3_1_0.security_requirement.SecurityScheme.

servers class-attribute instance-attribute

servers = None

A python list with dictionary compatible with OpenAPI specification.

tags class-attribute instance-attribute

tags = None

A list of OpenAPI compatible tag (string) information.

root_path_in_servers class-attribute instance-attribute

root_path_in_servers = True

A boolean flag indicating if the root path should be included in the servers.

docs_url class-attribute instance-attribute

docs_url = None

String default relative URL where the Swagger documentation shall be accessed in the application.

Example: '/docs/swagger`.

redoc_url class-attribute instance-attribute

redoc_url = None

String default relative URL where the ReDoc documentation shall be accessed in the application.

Example: '/docs/swagger`.

swagger_ui_oauth2_redirect_url class-attribute instance-attribute

swagger_ui_oauth2_redirect_url = None

String default relative URL where the Swagger UI OAuth Redirect URL shall be accessed in the application.

Example: /docs/oauth2-redirect.

redoc_js_url class-attribute instance-attribute

redoc_js_url = None

String default URL where the ReDoc Javascript is located and used within OpenAPI documentation,

Example: https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js.

redoc_favicon_url class-attribute instance-attribute

redoc_favicon_url = None

String default URL where the ReDoc favicon is located and used within OpenAPI documentation,

Example: https://esmerald.dev/statics/images/favicon.ico.

swagger_ui_init_oauth class-attribute instance-attribute

swagger_ui_init_oauth = None

String default relative URL where the Swagger Init Auth documentation shall be accessed in the application.

swagger_ui_parameters class-attribute instance-attribute

swagger_ui_parameters = None

A mapping with parameters to be passed onto Swagger.

swagger_js_url class-attribute instance-attribute

swagger_js_url = None

Boolean flag indicating if the google fonts shall be used in the ReDoc OpenAPI Documentation.

swagger_css_url class-attribute instance-attribute

swagger_css_url = None

String default URL where the Swagger Javascript is located and used within OpenAPI documentation,

Example: https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.1.3/swagger-ui-bundle.min.js.

swagger_favicon_url class-attribute instance-attribute

swagger_favicon_url = None

String default URL where the Swagger favicon is located and used within OpenAPI documentation,

Example: https://esmerald.dev/statics/images/favicon.ico.

with_google_fonts class-attribute instance-attribute

with_google_fonts = True

Boolean flag indicating if the google fonts shall be used in the ReDoc OpenAPI Documentation.

stoplight_js_url class-attribute instance-attribute

stoplight_js_url = None

Boolean flag indicating if the google fonts shall be used in the ReDoc OpenAPI Documentation.

stoplight_css_url class-attribute instance-attribute

stoplight_css_url = None

String default URL where the Stoplight CSS is located and used within OpenAPI documentation,

Example: https://unpkg.com/@stoplight/elements/styles.min.css.

stoplight_url class-attribute instance-attribute

stoplight_url = None

String default relative URL where the Stoplight documentation shall be accessed in the application.

Example: /docs/elements.

stoplight_favicon_url class-attribute instance-attribute

stoplight_favicon_url = None

String default URL where the Stoplight favicon is located and used within OpenAPI documentation,

Example: https://esmerald.dev/statics/images/favicon.ico.

rapidoc_url class-attribute instance-attribute

rapidoc_url = None

String default relative URL where the Rapidoc documentation shall be accessed in the application.

Example: /docs/rapidoc.

rapidoc_js_url class-attribute instance-attribute

rapidoc_js_url = None

String default URL where the Stoplight Javascript is located and used within OpenAPI documentation,

This is used as the default if no OpenAPIConfig is provided.

rapidoc_favicon_url class-attribute instance-attribute

rapidoc_favicon_url = None

String default URL where the RapiDoc favicon is located and used within OpenAPI documentation,

Example: https://esmerald.dev/statics/images/favicon.ico.

webhooks class-attribute instance-attribute

webhooks = None

This is the same principle of the routes but for OpenAPI webhooks.

Read more about webhooks.

When a webhook is added, it will automatically add them into the OpenAPI documentation.