OpenAPI Documentation

ASAB's API service generates Swagger documentation which automatically shows all of your endpoints, and you can add summaries, descriptions, tags, and more.

If you want authorization in Swagger docs, you will need an OpenIDConnect endpoint.

Creating OpenAPI endpoint

First, you need to initialize the API Service:

self.ApiService = asab.api.ApiService(self) #(1)!
self.ApiService.initialize_web() #(2)!

1. Initializes OpenAPI Service.
2. Introduces Web to OpenAPI Service.

After initializing the API Service, /doc endpoint will become available. After you open it, you should see the following content:

You will notice that some or none of your endpoints have summaries, tags, or descriptions.

That's because you need to add a docstring to your endpoint method:

async def endpoint(self, request):
    """
    Summary looks like this and takes the first line from docstring.

    Description of what this endpoint does.

    ---
    tags: [asab.my_microservice]
    """

Also by adding a docstring to your ASAB Application, a description will be automatically added to the top of the Swagger docs:

class TutorialApp(asab.Application):
    """
    TutorialApp is the best microservice in the world!

    <marquee>The description supports HTML tags</marquee>
    """

Describing parameters

OpenAPI 3.0 defines the parameters section format.

• path parameters (/user/{id}) are created automatically by the asab.api.APIService itself, with no description.
• query parameters (/users?role=admin) must be defined in the endpoint's docstring.

async def endpoint(self, request):
    """
    Summary.

    Description.

    ---
    parameters:
        -   name: id
            in: query
            description: Description of the query parameter.
            schema:
                type: string
    """

Authorization in Swagger

Authorization requires making an OpenIDConnect endpoint with an Authorization and Token endpoint (like with using TeskaLabs SeaCat Auth).

For authorization, you will need to add authorization_url and token_url to the configuration:

[asab:doc]
authorization_url=http://localhost:8080/openidconnect/authorize
token_url=http://localhost:8080/openidconnect/token

If you have an endpoint that requires a scope, you can add it with the configuration file:

[asab:doc]
scopes=read,write

To set up endpoint authorization, you can use this example.

For the authorization bearer token to be added to the request, a scope is needed to be put into the security parameter in a docstring. It does not matter what it is called or if it exists, but it needs to be included. - oAuth must always be included.

@asab.web.authz.required("resource:topsecret")
async def top_secret_endpoint(self, request):
    """
    Top secret!

    ---
    tags: [asab.coolest_microservice]
    security:
        - oAuth:
            - read
    """

After setting up Authorization, a green Authorize button should appear in the Swagger docs. After you click on it, you should see the following content:

Tags

You can label your handler methods with custom tags. These tags are used for grouping and sorting your endpoints on the documentation page.

async def my_method(self, request):
"""
<function description>

---
tags: ['custom tag 1', 'custom tag 2', 'custom tag 3']
"""
    ...

Info

Remember to use exactly three dashes on the separate line and put tags in array with [], even if you want to have a single tag.

If there is no custom tag defined, the tag name is automatically set to be module_name. If you do not want to use custom tags but still would like to sort the routes, you can configure the options in the configuration file:

[asab:doc]
default_route_tag=class_name

There are two options for default_route_tag:

module_nameclass_name

All tags without a custom name are displayed with the name of the module where the handler is defined.

All tags without a custom name are displayed with the name of the class where the handler is defined.