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 application right now.

Copy the following code in your basic.py file:

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:

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

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

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.

Note

The description field in the above example supports Markdown text.

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:

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

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

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:

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

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

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:

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

Copy the following code in your basic.py file, we have highlighted 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:

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 and serve it#

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

Generate the initial schema.json by running
```
faststream docs gen basic:app
```
Manually edit the asyncapi.json file to add custom fields, descriptions, and details.
Save your changes.
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!