Possible to generate AsyncAPI docs when running FastStream manually, as a regular async function?

[strock-dev]

Hi People,

I'm a student doing an intern and I'm currently facing a problem. My endgoal will be code-first event API documentation with the help of FastStream. I want to leverage it's capabilities to generate AsyncAPI documents from code so we can build our event docs via pipelines. Therefore I'm aiming to replace aio-pika with FastStream in a rather large distributed system with multiple rather large microservices which communicate via RabbitMQ.

For testing and exploration purposes I built a small application which consists of two services. One is just emitting events and the other is receiving events all via a default RabbitMQ broker. I figured that I'll probably need a way to run FastStream without it's CLI that's why I built it as shown in the tutorial.

When I now try to run faststream docs gen --out asyncapi-verifier.json verifier:app it gives me following error (which makes sense as I had to put the app attribute inside of main()

module 'verifier' has no attribute 'app'
Usage: faststream docs gen [OPTIONS] APP
Try 'faststream docs gen --help' for help.
╭─ Error 
│ Invalid value: Attribute "app" not found in module "verifier".

I didn't find a way to generate an AsyncAPI document in other ways. Did I miss something or do you know a possible solution?

[davorrunje]

@strock-dev Hi! Assuming that you wrote your verifier.py as:

import asyncio

app = None

def get_app():
    return app

def create_app():
    global app

    app = FastStream(...)

async def main():
    create_app()
    await app.run()  # blocking method

if __name__ == "__main__":
    asyncio.run(main())

then you can write verifier_doc.py in the same directory as:

from .verifier import create_app, get_app

create_app()
app = get_app()

and then run:

faststream docs gen --out asyncapi-verifier.json verifier_doc:app

Hope that helps. If not, please let me know.

[strock-dev]

Thanks so much for your input! I didn't test your solution as I came up with a somewhat 'hacky' workaround for my problem. I imported get_app_schema and called to_yaml() on that schema. After that I just wrote that yaml into a file.

from faststream.asyncapi import get_app_schema

schema_yaml = get_app_schema(app).to_yaml()

file = Path("output.yaml)
with file.open("w", encoding="utf-8") as f:
    f.write(schema_yaml)

Serving that yaml via FastStream worked for me. Another option is of course to use the AsyncAPI CLI to generate HTML from that file.

I'm unsure if I should mark your answer as correct, as I didn't test it by myself.

[Lancetnik]

You can do not use CLI and generate HTML representation from already created Schema (you made it correctly) - https://github.com/airtai/faststream/blob/main/faststream/asyncapi/site.py#L20

Or even run hosting from the code - https://github.com/airtai/faststream/blob/main/faststream/asyncapi/site.py#L105

Also, you can use AsgiFastStream object and run it with the documentation manully. Regular AsgiFastStream().run() - runs not just a broker, but an ASGI-HTTP endpoints as well

[strock-dev]

Good to know! Although I noticed that, when serving HTML via FastStream, my subscribers are marked as "PUB", which is not happening when generating HTML via AsyncAPI CLI.. So maybe that's a bug?

[Lancetnik]

@strock-dev what does "generating HTML via AsyncAPI CLI" means? How are you generates HTML?
Btw, we are using AsyncAPI React component CDN to draw HTML from our generated schema. If you generates HTML by AsyncAPI CLI from our schema too - incosistence should be a bug of CDN version, I think. Anyway, I'll investigate a little deeper if you provide some MRE

[strock-dev]

I'm speaking about this generator template which is using the official AsyncAPI CLI (Generator). It builds an HTML file from any AsyncAPI file.

I can look into this bug later this week, although I never participated in any open source project (and tbh never even did a merge request). I will see how it goes 😅👍