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 ravyn import OpenAPIConfig

ravyn.core.config.openapi.OpenAPIConfig

Bases: BaseModel

An instance of OpenAPIConfig.

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

Note: Here is where the defaults for Ravyn 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 ravyn import OpenAPIConfig

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

app = Ravyn(openapi_config=openapi_config)

Important

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

If the parameter is not specified, Ravyn 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 ravyn.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 ravyn.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 ravyn.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.

openapi_version class-attribute instance-attribute

openapi_version = None

The version of the OpenAPI being used. Ravyn uses the version 3.1.0 by default and tis can be useful if you want to trick some of the existing tools that require a lower version.

openapi_url class-attribute instance-attribute

openapi_url = None

URL of the openapi.json in the format of a path.

Example: /openapi.json.

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://ravyn.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://ravyn.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://ravyn.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://ravyn.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.

openapi

openapi(app)

Loads the OpenAPI routing schema

Source code in ravyn/core/config/openapi.py

def openapi(self, app: Any) -> dict[str, Any]:
    """Loads the OpenAPI routing schema"""
    openapi_schema = get_openapi(
        app=app,
        title=self.title,
        version=self.version,
        openapi_version=self.openapi_version,
        summary=self.summary,
        description=self.description,
        routes=app.routes,
        tags=self.tags,
        servers=self.servers,
        terms_of_service=self.terms_of_service,
        contact=self.contact,
        license=self.license,
        webhooks=self.webhooks,
    )
    app.openapi_schema = openapi_schema
    return cast(dict[str, Any], app.openapi_schema)

enable

enable(app)

Enables the OpenAPI documentation

Source code in ravyn/core/config/openapi.py

def enable(self, app: Any) -> None:
    """Enables the OpenAPI documentation"""
    if self.openapi_url:
        urls = {server.get("url") for server in self.servers}
        server_urls = set(urls)

        @get(path=self.openapi_url)
        async def _openapi(request: Request) -> JSONResponse:
            root_path = request.scope.get("root_path", "").rstrip("/")

            if root_path not in server_urls:
                if root_path and self.root_path_in_servers:
                    self.servers.insert(0, {"url": root_path})
                    server_urls.add(root_path)
            return JSONResponse(self.openapi(app))

        app.add_route(
            path="/",
            handler=_openapi,
            include_in_schema=False,
            activate_openapi=False,
        )

    if self.openapi_url and self.docs_url:

        @get(path=self.docs_url)
        async def swagger_ui_html(
            request: Request,
        ) -> HTMLResponse:  # pragma: no cover
            root_path = request.scope.get("root_path", "").rstrip("/")
            openapi_url = root_path + self.openapi_url
            oauth2_redirect_url = self.swagger_ui_oauth2_redirect_url
            if oauth2_redirect_url:
                oauth2_redirect_url = root_path + oauth2_redirect_url
            return get_swagger_ui_html(
                openapi_url=openapi_url,
                title=self.title + " - Swagger UI",
                oauth2_redirect_url=oauth2_redirect_url,
                init_oauth=self.swagger_ui_init_oauth,
                swagger_ui_parameters=self.swagger_ui_parameters,
                swagger_js_url=self.swagger_js_url,
                swagger_favicon_url=self.swagger_favicon_url,
                swagger_css_url=self.swagger_css_url,
            )

        app.add_route(
            path="/",
            handler=swagger_ui_html,
            include_in_schema=False,
            activate_openapi=False,
        )

    if self.swagger_ui_oauth2_redirect_url:

        @get(self.swagger_ui_oauth2_redirect_url)
        async def swagger_ui_redirect(
            request: Request,
        ) -> HTMLResponse:  # pragma: no cover
            return get_swagger_ui_oauth2_redirect_html()

        app.add_route(
            path="/",
            handler=swagger_ui_redirect,
            include_in_schema=False,
            activate_openapi=False,
        )

    if self.openapi_url and self.redoc_url:

        @get(self.redoc_url)
        async def redoc_html(request: Request) -> HTMLResponse:  # pragma: no cover
            root_path = request.scope.get("root_path", "").rstrip("/")
            openapi_url = root_path + self.openapi_url
            return get_redoc_html(
                openapi_url=openapi_url,
                title=self.title + " - ReDoc",
                redoc_js_url=self.redoc_js_url,
                redoc_favicon_url=self.redoc_favicon_url,
                with_google_fonts=self.with_google_fonts,
            )

        app.add_route(
            path="/",
            handler=redoc_html,
            include_in_schema=False,
            activate_openapi=False,
        )

    if self.openapi_url and self.stoplight_url:

        @get(self.stoplight_url)
        async def stoplight_html(
            request: Request,
        ) -> HTMLResponse:  # pragma: no cover
            root_path = request.scope.get("root_path", "").rstrip("/")
            openapi_url = root_path + self.openapi_url
            return get_stoplight_html(
                openapi_url=openapi_url,
                title=self.title + " - Stoplight Elements",
                stoplight_js=self.stoplight_js_url,
                stoplight_css=self.stoplight_css_url,
                stoplight_favicon_url=self.stoplight_favicon_url,
            )

        app.add_route(
            path="/",
            handler=stoplight_html,
            include_in_schema=False,
            activate_openapi=False,
        )

    if self.openapi_url and self.rapidoc_url:

        @get(self.rapidoc_url)
        async def rapidoc_html(
            request: Request,
        ) -> HTMLResponse:  # pragma: no cover
            root_path = request.scope.get("root_path", "").rstrip("/")
            openapi_url = root_path + self.openapi_url

            return get_rapidoc_ui_html(
                openapi_url=openapi_url,
                title=self.title + " - RapiDoc",
                rapidoc_js_url=self.rapidoc_js_url,
                rapidoc_favicon_url=self.rapidoc_favicon_url,
            )

        app.add_route(
            path="/",
            handler=rapidoc_html,
            include_in_schema=False,
            activate_openapi=False,
        )

    app.router.activate()

    - "!^openapi"
    - "!^enable"