Async API documentation 101

#documentation #api #nestjs #node

Async API documentation is used for documenting events in event-driven systems, like Kafka events. All of the event DTOs are stored in one place. It supports YAML and JSON formats.

It contains information about channels and components. Channels and components are defined with their messages and DTO schemas, respectively.

{
  "asyncapi": "2.6.0",
  "info": {
    "title": "Events docs",
    "version": "1.0.0"
  },
  "channels": {
    "topic_name": {
      "publish": {
        "message": {
          "schemaFormat": "application/vnd.oai.openapi;version=3.0.0",
          "payload": {
            "type": "object",
            "properties": {
              "counter": {
                "type": "number"
              }
            },
            "required": [
              "counter"
            ]
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EventDto": {
        "type": "object",
        "properties": {
          "counter": {
            "type": "number"
          }
        },
        "required": [
          "counter"
        ]
      }
    }
  }
}

Autogeneration

Async API docs can be autogenerated by following multiple steps:

define DTOs and their required and optional fields with ApiProperty and ApiPropertyOptional decorators (from the @nestjs/swagger package), respectively
generate OpenAPI docs from the defined DTOs
parse and reuse component schemas from generated OpenAPI documentation to build channel messages and component schemas for Async API docs

Validation

Use AsyncAPI Studio to validate the written specification.

Preview

There are multiple options

AsyncAPI Studio
VSCode extension asyncapi-preview, open the command palette, and run the Preview AsyncAPI command.

UI generation

Install @asyncapi/cli and corresponding template package (e.g., @asyncapi/html-template, @asyncapi/markdown-template)
Update package.json with scripts

{
  "scripts": {
    // ...
    "generate-docs:html": "asyncapi generate fromTemplate ./asyncapi/asyncapi.json @asyncapi/html-template --output ./docs/html",
    "generate-docs:markdown": "asyncapi generate fromTemplate ./asyncapi/asyncapi.json @asyncapi/markdown-template --output ./docs/markdown"
  }
}