Customizing AsyncAPI Documentation for FastStream#

In this guide, we will explore how to customize AsyncAPI documentation for your FastStream application. Whether you want to add custom app info, broker information, handlers, or fine-tune payload details, we'll walk you through each step.

Prerequisites#

Before we dive into customization, ensure you have a basic FastStream application up and running. If you haven't done that yet, let's setup a simple appication right now.

Copy the following code in your basic.py file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

    from faststream import FastStream
    from faststream.kafka import KafkaBroker, KafkaMessage

    broker = KafkaBroker("localhost:9092")
    app = FastStream(broker)

    @broker.publisher("output_data")
    @broker.subscriber("input_data")
    async def on_input_data(msg):
        # your processing logic
        pass

Now, when you run faststream docs serve basic:app you should see the following documentation:

Setup Custom FastStream App Info#

Let's start by customizing the app information that appears in your AsyncAPI documentation. This is a great way to give your documentation a personal touch. Here's how:

1. Locate the app configuration in your FastStream application.
2. Update the title, version, and description fields to reflect your application's details.
3. Save the changes.
4. Serve your FastStream app documentation.

Copy the following code in your basic.py file, we have highligted the additional info passed to FastStream app:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

    from faststream import FastStream
    from faststream.kafka import KafkaBroker, KafkaMessage
    from faststream.asyncapi.schema import Contact, ExternalDocs, License, Tag

    broker = KafkaBroker("localhost:9092")
    description="""# Title of the description
    This description supports **Markdown** syntax"""
    app = FastStream(broker,
                title="My App",
                version="1.0.0",
                description=description,
                license=License(name="MIT", url="https://opensource.org/license/mit/"),
                terms_of_service="https://my-terms.com/",
                contact=Contact(name="support", url="https://help.com/"),
            )

    @broker.publisher("output_data")
    @broker.subscriber("input_data")
    async def on_input_data(msg):
        # your processing logic
        pass

Now, when you run faststream docs serve basic:app you should see the following in your general app documentation:

Now, your documentation reflects your application's identity and purpose.

Setup Custom Broker Information#

The next step is to customize broker information. This helps users understand the messaging system your application uses. Follow these steps:

1. Locate the broker configuration in your FastStream application.
2. Update the description field.
3. Update the asyncapi_url field with a non-sensitive URL if you want to conceal your broker's actual bootstrap server URL.
4. Save the changes.
5. Serve your FastStream app.

Copy the following code in your basic.py file, we have highligted the additional info passed to the FastStream app broker:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

    from faststream import FastStream
    from faststream.kafka import KafkaBroker, KafkaMessage
    from faststream.asyncapi.schema import Tag

    broker = KafkaBroker(
        "localhost:9092",
        description="Kafka broker running locally",
        asyncapi_url="non-sensitive-url:9092",
    )
    app = FastStream(broker)


    @broker.publisher("output_data")
    @broker.subscriber("input_data")
    async def on_input_data(msg):
        # your processing logic
        pass

Now, when you run faststream docs serve basic:app you should see the description in your broker documentation:

Your AsyncAPI documentation now provides clear insights into the messaging infrastructure you're using.

Setup Custom Handler Information#

Customizing handler information helps users comprehend the purpose and behavior of each message handler. Here's how to do it:

1. Navigate to your handler definitions in your FastStream application.
2. Add descriptions to each handler using description field.
3. For subscriber, consumer function's docstring can be used as description.
4. Add titles to each handler using title field adhering to URI format.
5. Add publishing schema to publisher handler using schema field.
6. Save the changes.
7. Serve your FastStream app.

Copy the following code in your basic.py file, we have highligted the additional info passed to the FastStream app handlers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

    from pydantic import BaseModel, Field, NonNegativeFloat

    from faststream import FastStream
    from faststream.kafka import KafkaBroker, KafkaMessage


    class DataBasic(BaseModel):
        data: NonNegativeFloat = Field(
            ..., examples=[0.5], description="Float data example"
        )


    broker = KafkaBroker("localhost:9092")
    app = FastStream(broker)


    @broker.publisher(
        "output_data",
        description="My publisher description",
        title="output_data:Produce",
        schema=DataBasic,
    )
    @broker.subscriber(
        "input_data", title="input_data:Consume"
    )
    async def on_input_data(msg):
        """Consumer function

        Args:
            msg: input msg
        """
        # your processing logic
        pass

Now, when you run faststream docs serve basic:app you should see the descriptions in your handlers:

Now, your documentation is enriched with meaningful details about each message handler.

Setup Payload Information via Pydantic Model#

To describe your message payload effectively, you can use Pydantic models. Here's how:

1. Define Pydantic models for your message payloads.
2. Annotate these models with descriptions and examples.
3. Use these models as argument types or return types in your handlers.
4. Save the changes.
5. Serve your FastStream app.

Copy the following code in your basic.py file, we have highligted the creation of payload info and you can see it being passed to the return type and the msg argument type in the on_input_data function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

    from pydantic import BaseModel, Field, NonNegativeFloat

    from faststream import FastStream
    from faststream.kafka import KafkaBroker


    class DataBasic(BaseModel):
        data: NonNegativeFloat = Field(
            ..., examples=[0.5], description="Float data example"
        )


    broker = KafkaBroker("localhost:9092")
    app = FastStream(broker)


    @broker.publisher("output_data")
    @broker.subscriber("input_data")
    async def on_input_data(msg: DataBasic) -> DataBasic:
        # your processing logic
        pass

Now, when you run faststream docs serve basic:app you should see the payload schema described in your documentation:

Your AsyncAPI documentation now showcases well-structured payload information.

Generate Schema.json, Customize Manually, and Serve It#

To take customization to the next level, you can manually modify the schema.json file. Follow these steps:

1. Generate the initial schema.json by running faststream docs gen basic:app.
2. Manually edit the asyncapi.json file to add custom fields, descriptions, and details.
3. Save your changes.
4. Serve your FastStream app with the updated asyncapi.json by running faststream docs serve asyncapi.json.

Now, you have fine-tuned control over your AsyncAPI documentation.

Conclusion#

Customizing AsyncAPI documentation for your FastStream application not only enhances its appearance but also provides valuable insights to users. With these steps, you can create documentation that's not only informative but also uniquely yours.

Happy coding with your customized FastStream AsyncAPI documentation!