Message examples object extended with additional fields
Thanks to work done by Laurent Broudoux, you can now clearly describe message examples. New properties name and summary are optional. These properties help not only to properly describe the example in documentation but make it easier to work with mocking and testing tools (like microcks), so you can better identify what example to use for mocking and what it does.
Example of new properties added to existing WebSocket example for Gemini API:
1components: 2 messages: 3 marketData: 4 summary: Message with marked data information. 5 description: | 6 The initial response message will show the existing state of the order book. Subsequent messages will show all executed trades, as well as all other changes to the order book from orders placed or canceled. 7 payload: 8 $ref: '#/components/schemas/market' 9 examples: 10 - name: updateMessage 11 summary: Example of an update message that contains a change in price information. 12 payload: 13 type: update 14 eventId: 36902233362 15 timestamp: 1619769673 16 timestampms: 1619769673527 17 socket_sequence: 661 18 events: 19 - type: change 20 side: bid 21 price: '54350.40' 22 remaining: '0.002' 23 delta: '0.002' 24 reason: place 25 - name: heartbeatMessage 26 summary: Example of additional heartbeat message when you enable them. 27 payload: 28 type: heartbeat 29 socket_sequence: 1656
Rendering of new example properties in React component and HTML template:
For more details, check out this pull request.
New protocol bindings
The specification is now extended to support the following custom protocols through the bindings feature:
- Mercure, thanks to Kévin Dunglas. At the moment, no specific bindings are necessary for this protocol. For more details, check out this pull request and binding definition.
- IBM MQ, thanks to Dale Lane and Richard Coppen. For more details check out this pull request and binding definition.
Custom schema formats mandatory vs recommended
New security schemes
Old new defaultContentType property in root object
We used and supported defaultContentType property to specify the default content type when encoding/decoding a message's payload. Lucas Block spotted that we do not have it defined in the specification. For more details, check out this pull request.
The following official AsyncAPI tools are already updated to support 2.1.0 version of the specification:
- JSON Schema that supports validation of AsyncAPI documents is updated in this repository. Also @asyncapi/specs package has been updated on NPM to version 2.8.0, and it contains the 2.1.0 JSON Schema.
- AsyncAPI Generator uses the latest @asyncapi/parser package, so while generating output, it can validate 2.1.0 documents. Upgrade to 1.8.0 version
- Generator filters functions getPayloadExamples and getHeadersExamples support new message example properties. Upgrade to 2.0.0 version.
- React component supports rendering of new message example properties. Upgrade to v1.0.0-next.10 version.
- Markdown template supports rendering of new message example properties. Upgrade to 0.14.0 version.
- HTML template uses the latest @asyncapi/react-component package. Upgrade to 0.23.0 version.
- Modelina now also accepts AsyncAPI documents valid against the 2.1.0 version of the spec. Upgrade to 0.16.0 version.
Last but not least is the AsyncAPI Playground. Check new playground that uses latest HTML template and Markdown template with this example.
I want to send a special thank you to Aayush Kumar Sahu