asynchronousyamldocumentationdocumentation-generationasyncapi

Missing generated example payload with AsyncAPI


I started using AsyncAPI to generate documentation for my asynchronous websocket protocol. I use AsyncAPI Studio to quickly iterate on my documentation and use asyncapi/cli with docker to actually generate the html on my local machine.

However, I'm running into a problem where the example payload isn't being generated (both on Studio and locally with docker-based CLI). I've tried different variations of example, examples, default , etc. in the schema but no matter what happens, I'm only getting a blank payload example.

blank payload example generated by AsyncAPI Studio

Any help would be greatly appreciated!

asyncapi: 3.0.0
info:
  title: Promotion-API
  version: 1.0.0
  description: >-
    WebSocket API for Client interactions with the Server.
  
  contact:
    name: Example Company
    url: https://www.example.com
    email: dev@example.com
  license:
    name: TBD
    url: https://www.example.com/LICENSE.txt
  
defaultContentType: application/json

servers:
  local:
    host: '<server-ip>:5111'
    protocol: ws
    title: Server
    summary: erver
    description: >-
      This API exists on a local server and can be accessed by others on the same local network.
    protocolVersion: "1.0"
    tags:
      - name: local
        description: local server
    bindings:
      ws:
        pingPongInterval: 20 seconds

channels:
  client:
    address: "client/{clientId}"
    parameters:
      clientId:
        $ref: '#/components/parameters/clientId'
    messages:
      BeginAction:
        $ref: '#/components/messages/BeginAction'

operations:
  begin:
    action: send
    title: Begin Action
    summary: Begin Transaction Action
    description: Notify the system that a new transaction begins.
    channel: 
      $ref: '#/channels/client'
    messages:
      - $ref: '#/channels/client/messages/BeginAction'
    tags:
      - name: transaction-action

components:
  schemas:
    transactionNumber:
      type: integer
      description: a 4 digit transaction number. Generally unique to the client at that date.
      example: 50
    userId:
      type: integer
      description: unique identifier of the user.
      example: 100
    BeginSchema:
      type: object
      properties:
        transactionNumber:
          $ref: '#/components/schemas/transactionNumber'
        "action":
          type: string
          description: the action string
          enum:
            - "begin"
          example: "begin"
        userId:
          $ref: '#/components/schemas/userId'
      required:
        - transactionNumber
        - action

  messages:
    BeginAction:
      name: BeginAction
      title: Begin Action Message
      summary: >-
        Message informing the server that a new transaction begins
      contentType: application/json
      payload:
        schema: 
          $ref: '#/components/schemas/BeginSchema'

  parameters:
    clientId:
      description: the unique id of the client.
      examples: ["1", "2", "100"]

Solution

  • Posted to AsyncAPI GitHub: https://github.com/orgs/asyncapi/discussions/1535

    But in the end found the answer myself:

    there was an extra schema field:

    bad:

    components:
      messages:
        BeginAction:
          name: BeginAction
          title: Begin Action Message
          summary: >-
            Message informing the server that a new transaction begins
          contentType: application/json
          payload:
            schema:
              $ref: '#/components/schemas/BeginSchema'
    

    good:

    components:
      messages:
        BeginAction:
          name: BeginAction
          title: Begin Action Message
          summary: >-
            Message informing the server that a new transaction begins
          contentType: application/json
          payload:
            $ref: '#/components/schemas/BeginSchema'