Skip to content

Serving the AsyncAPI Docs

Serve docs from an already created spec

asyncapi: 2.0.0

info:
  title: User API
  version: '1.0.0'
  description: API to manage users

servers:
  development:
    url: localhost
    protocol: redis
    description: Development Broker Server

channels:
  user/update:
    description: Topic for user updates
    subscribe:
      operationId: receive_user_update
      message:
        $ref: '#/components/messages/UserUpdate'
    publish:
      message:
        $ref: '#/components/messages/UserUpdate'

components:
  messages:
    UserUpdate:
      name: userUpdate
      title: User Update
      summary: Inform about users updates
      payload:
        type: object
        required:
          - id
        properties:
          id:
            type: string
          name:
            type: string
          age:
            type: integer

defaultContentType: application/json
asyncapi-docs --path api-spec.yaml
INFO:     Started server process [...]
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO:     Shutting down
INFO:     Finished server process [...]

Create subscriber module

# user_events.py

from typing import Any


async def receive_user_update(message: Any) -> None:
    print(f"Received update for user id={message.id}")

Start subscriber to listen events from exposed spec

PYTHONPATH=. asyncapi-subscriber \
    --url http://localhost:5000/asyncapi.json \
    --api-module user_events

Publishing updates from exposed spec

# publish.py

import asyncio

from asyncapi import build_api


api = build_api('http://localhost:5000/asyncapi.yaml')
channel_id = 'user/update'
message = api.payload(channel_id, id='fake-user', name='Fake User', age=33)


async def publish() -> None:
    await api.connect()
    await api.publish(channel_id, message)
    await api.disconnect()


asyncio.run(publish())

print(f"Published update for user={message.id}")
python publish.py

Published update for user=fake-user

Receive Updates

Waiting messages...
Received update for user id=fake-user

Request YAML Specification

curl -i localhost:5000/asyncapi.yaml
HTTP/1.1 200 OK
date: ...
server: uvicorn
content-type: application/x-yaml
content-length: 833

asyncapi: 2.0.0
channels:
  user/update:
    description: Topic for user updates
    publish:
      message:
        $ref: '#/components/messages/UserUpdate'
    subscribe:
      message:
        $ref: '#/components/messages/UserUpdate'
      operationId: receive_user_update
components:
  messages:
    UserUpdate:
      name: userUpdate
      payload:
        properties:
          age:
            type: integer
          id:
            type: string
          name:
            type: string
        required:
        - id
        type: object
      summary: Inform about users updates
      title: User Update
defaultContentType: application/json
info:
  description: API to manage users
  title: User API
  version: 1.0.0
servers:
  development:
    description: Development Broker Server
    protocol: redis
    url: localhost

Request JSON Specification

curl -i localhost:5000/asyncapi.json
HTTP/1.1 200 OK
date: ...
server: uvicorn
content-type: application/json
content-length: 1231

{
  "info": {
    "title": "User API",
    "version": "1.0.0",
    "description": "API to manage users"
  },
  "channels": {
    "user/update": {
      "description": "Topic for user updates",
      "publish": {
        "message": {
          "$ref": "#/components/messages/UserUpdate"
        }
      },
      "subscribe": {
        "operationId": "receive_user_update",
        "message": {
          "$ref": "#/components/messages/UserUpdate"
        }
      }
    }
  },
  "servers": {
    "development": {
      "url": "localhost",
      "protocol": "redis",
      "description": "Development Broker Server"
    }
  },
  "components": {
    "messages": {
      "UserUpdate": {
        "payload": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "age": {
              "type": "integer"
            }
          },
          "required": [
            "id"
          ]
        },
        "name": "userUpdate",
        "title": "User Update",
        "summary": "Inform about users updates"
      }
    }
  },
  "defaultContentType": "application/json",
  "asyncapi": "2.0.0"