Skip to content

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:

Preview of Swagger documentation

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>
Preview of Swagger documentation with docstrings

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):


        -   name: id
            in: query
            description: Description of the query parameter.
                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:


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


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.

async def top_secret_endpoint(self, request):
    Top secret!

    tags: [asab.coolest_microservice]
        - 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:

Authorization of Swagger documentation


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']


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:


There are two options for default_route_tag:

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

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