Документирование

Propan позволяет вам не думать о документации своего проекта - она уже сгенерирована автоматически в соответсвии со спецификацией AsyncAPI!

Для работы с документацией вам необходимо установить дополнительные зависимости:

pip install "propan[doc]"

Пример

Давайте разберемся на примере, как это работает.

Для начала напишем небольшое приложение примерно следующего содержания:

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 схема

Для того, чтобы сгенерировать AsyncAPI спецификацию вашего проекта в формате .yaml используйте следующую команду:

$ propan docs gen example:app

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

Теперь у вас есть схема вашего проекта: вы можете использовать ее для генерации различных клиентов на любом языке с помощью соответсвующих инструментов AsyncAPI

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

Онлайн документация

Также, Propan позволяет вам развернуть HTML-представление вашей документации следующей командой

Онлайн представлени документации не работает без интернет-соединения, так как для ее отображения используются CDN зависимости.

$ propan docs serve example:app

Так вы можете предоставить всем внешним потребителям доступ к документации вашего проекта без дополнительных затрат на разработку.

HTML page

Tip

Propan также можете хостить asyncapi.yaml файлы.

propan docs serve asyncapi.yaml

Это может быть полезно если вы хотите расширить автоматически сгенерированную AsyncAPI документацию: вы просто генерирует файл, дорабатываете его и хостите!

При использовании онлайн документации вы также можете скачать ее по соответствующим путям:

• /asyncapi.json - JSON схема (доступно при хостинге приложения)
• /asyncapi.yaml - YAML схема (доступна как для приложения, так и для файла)

FastAPI Plugin

При использовании Propan в качестве роутера для FastAPI, фреймворк автоматически регистрирует эндпоинты для хостинга AsyncAPI документации в ваше приложение со следующими значениями по умолчанию:

from propan.fastapi import RabbitRouter

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

Собственный хостинг

Для хостинга документации онлайн Propan использует FastAPI + uvicorn. Возможно, вы захотите самостоятельно реализовать логику показа документации: ограничить права доступа, кастомизировать контент в заивисмоти от прав доступа, встроить документацию в свое frontend-приложение и тд. Для это вы можете самостоятельно сгенерировать json/yaml/html документ и использовать в собственном сервисе.

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)