how to configure security schemes using open API handler?

[amirongit]

so I have configured a JWTBearerAuthentication for my app and it is working fine.
but how can I include this in the openAPI document generated by OpenAPIHandler?

currently, I have no ways to fill the Authorization header in my swagger UI, is it supported?

reference: https://swagger.io/docs/specification/authentication/

[amirongit]

this is my workaround. (used @tyzhnenko 's reply to improve it)

is this the proper way?
what if I wanted to exclude a route from it?
I'm still thinking that it is not developed yet. (or not documented, idk)

from blacksheep.server.openapi.v3 import OpenAPIHandler
from openapidocs.v3 import HTTPSecurity, Info, OpenAPI, Security, SecurityRequirement


class PatchedOpenAPIHandler(OpenAPIHandler):
    def on_docs_generated(self, docs: OpenAPI) -> None:
        docs.components.security_schemes = {'KCAccessToken': HTTPSecurity(scheme='bearer', bearer_format='JWT')}
        docs.security = Security(requirements=[SecurityRequirement(name='KCAccessToken', value=list())])
        super().on_docs_generated(docs)

[tyzhnenko]

@amirongit to ignore a handler you can use ignore decorator from OpenAPIHandler instance

Here's an example from the documentation

@docs.ignore()
@app.route("/hidden-from-docs")
async def hidden_endpoint():
    return "This endpoint won't appear in documentation"

[amirongit]

I meant "excluding" a handler from having authentication.
like what allow_anonymous does, but in the documentation, not ignoring the whole handler altogether.

[tyzhnenko]

@amirongit got it. You're right currently such a feature is not supported. This requires changes in OpenAPIHandler to set the empty security config into a path description.

[tyzhnenko]

I have this workaround for my password flow.

class AppOpenAPIHandler(OpenAPIHandler):
    def on_docs_generated(self, docs: OpenAPI) -> None:
        docs.security = Security([SecurityRequirement("oauth2", [])])
        assert docs.components is not None
        docs.components.security_schemes = {
            "oauth2": OAuth2Security(
                flows=OAuthFlows(
                    password=OAuthFlow(
                        token_url="/api/auth/token",
                        refresh_url="/api/auth/refresh",
                        scopes={},
                    )
                ),
                description="OAuth2 Auth",
            ),
        }



docs = AppOpenAPIHandler(
    info=Info(
        title=configuration.app_name,
        version=configuration.version,
        description=configuration.description,
    )
)
docs.bind_app(app)

[tyzhnenko]

@amirongit I realized that docs decorator contains on_create hook. It can be used to custom-tune an Operation attribute.

BlackSheep v2 - https://github.com/Neoteroi/BlackSheep/blob/main/blacksheep/server/openapi/v3.py#L1139-L1140
BlackSheep v1 – https://github.com/Neoteroi/BlackSheep/blob/v1/blacksheep/server/openapi/v3.py#L961-L962

def unsecure_handler(self, operation):
    operation.security = []

@docs(on_create=unsecure_handler)
@allow_anonymous
@app.route("/")
async def home():
    return "OpenAPI Example"

[amirongit]

thanks