Documenting

Propan allows you not to think about the documentation of your project - it is already generated automatically in accordance with the AsyncAPI specification !

To work with a documentation you should install an extra requirements:

pip install "propan[doc]"

Example

Let's look at an example.

To begin with, we will write a small application with the following content:

from propan import PropanApp, RabbitBroker
from propan.brokers.rabbit import RabbitQueue, RabbitExchange, ExchangeType

broker = RabbitBroker()
app = PropanApp(
    broker=broker,
    title="Smartylighting Streetlights Propan API",
    version="1.0.0",
    description="""
    The Smartylighting Streetlights API.
    ### Check out its awesome features:
    * Turn a specific streetlight on/off 🌃
    * Receive real-time information about environmental 📈
    """
)

@broker.handle(
    queue=RabbitQueue("*.info", durable=True),
    exchange=RabbitExchange("logs", durable=True, type=ExchangeType.TOPIC)
)
async def handle_logs(level: int, message: str = ""):
    """Handle all environmental events"""
    ...

YAML schema

To generate the AsyncAPI specification of your project in the .yaml format use the following command:

$ propan docs gen example:app

Your project AsyncAPI scheme was placed to `./asyncapi.yaml`

Now you have a scheme of your project: you can use it to generate various clients in any language using an AsyncAPI tools.

Asyncapi.yaml

asyncapi: 2.6.0
defaultContentType: application/json
info:
  title: Smartylighting Streetlights Propan API
  version: 1.0.0
  description: "\n    The Smartylighting Streetlights API.\n    ### Check out its\
    \ awesome features:\n    * Turn a specific streetlight on/off \U0001F303\n   \
    \ * Receive real-time information about environmental \U0001F4C8\n    "
servers:
  dev:
    url: amqp://guest:guest@localhost:5672/
    protocol: amqp
    protocolVersion: 0.9.1
channels:
  HandleLogs:
    servers:
    - dev
    bindings:
      amqp:
        is: routingKey
        bindingVersion: 0.2.0
        queue:
          name: '*.info'
          durable: true
          exclusive: false
          autoDelete: false
          vhost: /
        exchange:
          name: logs
          type: topic
          durable: true
          autoDelete: false
          vhost: /
    subscribe:
      description: Handle all environmental events
      bindings:
        amqp:
          cc: '*.info'
          ack: true
          bindingVersion: 0.2.0
      message:
        $ref: '#/components/messages/HandleLogsMessage'
components:
  messages:
    HandleLogsMessage:
      title: HandleLogsMessage
      correlationId:
        location: $message.header#/correlation_id
      payload:
        $ref: '#/components/schemas/HandleLogsPayload'
  schemas:
    HandleLogsPayload:
      title: HandleLogsPayload
      type: object
      properties:
        level:
          title: Level
          type: integer
        message:
          title: Message
          default: ''
          type: string
      required:
      - level
      example:
        level: 4015
        message: evwWheCeRIGhHEHYxKSJ

Online documentation

Also, Propan allows you to host HTML representation of your documentation with the following command

The online representation of documentation does not work without an internet connection, since CDN dependencies are used to display it.

$ propan docs serve example:app

This way you can provide all external consumers with access to your project documentation without additional development costs.

HTML page

Tip

Propan can also host asyncapi.yaml files.

propan docs serve asyncapi.yaml

This can be useful if you want to extend the automatically generated AsyncAPI documentation: you just generate a file, modify and host it!

When using online documentation, you can also download it using the following paths:

• /asyncapi.json - JSON schema (available when hosting an application)
• /asyncapi.yaml - YAML schema (available for an application and a file both)

FastAPI Plugin

When using Propan as a router for FastAPI, the framework automatically registers endpoints for hosting AsyncAPI documentation in your application with the following default values:

from propan.fastapi import RabbitRouter

router = RabbitRouter(
    schema_url="/asyncapi",
    include_in_schema=True,
)

Own hosting

For hosting documentation Propan uses FastAPI + uvicorn. You may want to implement the logic of displaying documentation yourself: restrict access rights, customize content regardless of access rights, embed documentation in your frontend application, and so on. To do this, you can generate a json/yaml/html document yourself and use it in your own service.

from propan import PropanApp, RabbitBroker
from propan.asyncapi.main import AsyncAPISchema
from propan.cli.docs.gen import gen_app_schema_json, gen_app_schema_yaml, get_app_schema
from propan.cli.docs.serving import get_asyncapi_html

broker = RabbitBroker()
app = PropanApp(broker)

schema: AsyncAPISchema = get_app_schema(app)
json_schema = gen_app_schema_json(app)
yaml_schema = gen_app_schema_yaml(app)
html = get_asyncapi_html(yaml_schema)