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.
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"]
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'