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
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.
class-attribute
instance-attribute
¶
summary = None
Simple and short summary text of the application/API.
class-attribute
instance-attribute
¶
description = None
A longer and more descriptive explanation of the application/API documentation.
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 openapi_schemas_pydantic.v3_1_0.contact.Contact.
class-attribute
instance-attribute
¶
terms_of_service = None
URL to a page that contains terms of service.
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 openapi_schemas_pydantic.v3_1_0.license.License.
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 openapi_schemas_pydantic.v3_1_0.security_requirement.SecurityScheme.
class-attribute
instance-attribute
¶
servers = None
A python list with dictionary compatible with OpenAPI specification.
class-attribute
instance-attribute
¶
tags = None
A list of OpenAPI compatible tag (string) information.
class-attribute
instance-attribute
¶
root_path_in_servers = True
A boolean flag indicating if the root path should be included in the servers.
class-attribute
instance-attribute
¶
docs_url = None
String default relative URL where the Swagger documentation shall be accessed in the application.
Example: '/docs/swagger`.
class-attribute
instance-attribute
¶
redoc_url = None
String default relative URL where the ReDoc documentation shall be accessed in the application.
Example: '/docs/swagger`.
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.
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.
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.
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.
class-attribute
instance-attribute
¶
swagger_ui_parameters = None
A mapping with parameters to be passed onto Swagger.
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.
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.
class-attribute
instance-attribute
¶
with_google_fonts = True
Boolean flag indicating if the google fonts shall be used in the ReDoc OpenAPI Documentation.
class-attribute
instance-attribute
¶
stoplight_js_url = None
Boolean flag indicating if the google fonts shall be used in the ReDoc OpenAPI Documentation.
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.
class-attribute
instance-attribute
¶
stoplight_url = None
String default relative URL where the Stoplight documentation shall be accessed in the application.
Example: /docs/elements.
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.
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.