Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update examples to be written by human not converter #977

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,14 @@

In this directory, you can find some examples of AsyncAPI documents.

**Do you have an example that could be valuable?** Open a pull request to contribute it.
**Do you have an example that could be valuable?** Open a pull request to contribute it.

## File naming

You may notice `asyncapi` in the the name of each example. We recommend doing the same with your AsyncAPI document. This way you enable features like documentation display on node hover, auto completion and validation of your AsyncAPI documents in IDEs like VSCode or IntelliJ IDEA. IDEs integrate with [SchemaStore](https://www.schemastore.org/json/) where AsyncAPI specification JSON Schema files are referenced. Some IDEs do it by default, some, like VSCode require you to install additional extensions, like `YAML` extension.

## Editors

To edit your AsyncAPI documents, you can use [AsyncAPI Studio](https://studio.asyncapi.com/).

If you prefer to use your favourite IDE, there are official extensions for [VSCode](https://marketplace.visualstudio.com/items?itemName=asyncapi.asyncapi-preview) and [IntelliJ IDEA](https://plugins.jetbrains.com/plugin/15673-asyncapi)
2 changes: 1 addition & 1 deletion examples/anyof.yml → examples/anyof-asyncapi.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,4 @@ components:
type: object
properties:
key2:
type: string
type: string
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ servers:
- '1883'
- '8883'
channels:
'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured':
lightingMeasured:
address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured'
messages:
receiveLightMeasurement.message:
lightMeasured:
$ref: '#/components/messages/lightMeasured'
parameters:
streetlightId:
Expand All @@ -32,8 +32,7 @@ operations:
receiveLightMeasurement:
action: receive
channel:
$ref: >-
#/channels/smartylighting~1streetlights~11~10~1event~1{streetlightId}~1lighting~1measured
$ref: '#/channels/lightingMeasured'
summary: >-
Inform about environmental lighting conditions of a particular
streetlight.
Expand Down Expand Up @@ -84,4 +83,4 @@ components:
type: string
parameters:
streetlightId:
description: The ID of the streetlight.
description: The ID of the streetlight.
Original file line number Diff line number Diff line change
Expand Up @@ -56,18 +56,18 @@ servers:
- 'streetlights:dim'
- $ref: '#/components/securitySchemes/openIdConnectWellKnown'
channels:
'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured':
lightingMeasured:
address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured'
messages:
receiveLightMeasurement.message:
lightMeasured:
$ref: '#/components/messages/lightMeasured'
parameters:
streetlightId:
$ref: '#/components/parameters/streetlightId'
'smartylighting/streetlights/1/0/action/{streetlightId}/dim':
lightsDim:
address: 'smartylighting/streetlights/1/0/action/{streetlightId}/dim'
messages:
dimLight.message:
dimLight:
$ref: '#/components/messages/dimLight'
parameters:
streetlightId:
Expand All @@ -76,8 +76,7 @@ operations:
receiveLightMeasurement:
action: receive
channel:
$ref: >-
#/channels/smartylighting~1streetlights~11~10~1event~1{streetlightId}~1lighting~1measured
$ref: '#/channels/lightingMeasured'
summary: >-
Inform about environmental lighting conditions of a particular
streetlight.
Expand All @@ -86,8 +85,7 @@ operations:
dimLight:
action: send
channel:
$ref: >-
#/channels/smartylighting~1streetlights~11~10~1action~1{streetlightId}~1dim
$ref: '#/channels/lightsDim'
messages:
- $ref: '#/components/messages/dimLight'
components:
Expand Down Expand Up @@ -179,4 +177,4 @@ components:
'streetlights:dim': Ability to dim the lights
openIdConnectWellKnown:
type: openIdConnect
openIdConnectUrl: 'https://authserver.example/.well-known'
openIdConnectUrl: 'https://authserver.example/.well-known'
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,12 @@ servers:
security:
- $ref: '#/components/securitySchemes/httpBearerToken'
channels:
'/rooms/{roomId}/{resource}':
rooms:
address: '/rooms/{roomId}/{resource}'
messages:
subscribe.message.0:
chatMessage:
$ref: '#/components/messages/chatMessage'
subscribe.message.1:
heartbeat:
$ref: '#/components/messages/heartbeat'
parameters:
roomId:
Expand All @@ -30,10 +30,10 @@ channels:
- events
description: The resource to consume.
operations:
'/rooms/{roomId}/{resource}.subscribe':
sendRoomInfo:
action: send
channel:
$ref: '#/channels/~1rooms~1{roomId}~1{resource}'
$ref: '#/channels/rooms'
bindings:
http:
type: response
Expand Down Expand Up @@ -148,7 +148,15 @@ components:
description: Stands for "Gravatar version" and is used for cache busting.
bindings:
http:
$ref: '#/components/messageBindings/streamingHeaders'
headers:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

$ref no supported in http header

type: object
properties:
Transfer-Encoding:
type: string
const: chunked
Trailer:
type: string
const: \r\n
heartbeat:
summary: Its purpose is to keep the connection alive.
payload:
Expand All @@ -159,10 +167,12 @@ components:
- "\r\n"
bindings:
http:
$ref: '#/components/messageBindings/streamingHeaders'
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ref not supported in header + it must be a json schema

messageBindings:
streamingHeaders:
http:
headers:
Transfer-Encoding: chunked
Trailer: \r\n
headers:
type: object
properties:
Transfer-Encoding:
type: string
const: chunked
Trailer:
type: string
const: \r\n
Original file line number Diff line number Diff line change
Expand Up @@ -36,76 +36,107 @@ channels:
$ref: '#/components/messages/subscribe'
unsubscribe:
$ref: '#/components/messages/unsubscribe'
dummyCurrencyInfo:
$ref: '#/components/messages/dummyCurrencyInfo'


operations:
pingPong:
action: send
receivePing:
action: receive
channel:
$ref: '#/channels/currencyExchange'
reply:
channel:
$ref: '#/channels/currencyExchange'
messages:
- $ref: '#/components/messages/ping'
heartbeat:
action: receive
- $ref: '#/components/messages/pong'
messages:
- $ref: '#/components/messages/ping'
sendHeartbeat:
action: send
channel:
$ref: '#/channels/currencyExchange'
$ref: '#/channels/currencyExchange'
messages:
- $ref: '#/components/messages/heartbeat'
systemStatus:
action: receive
channel:
$ref: '#/channels/currencyExchange'
subscribe:
action: send
channel:
$ref: '#/channels/currencyExchange'
messages:
- $ref: '#/components/messages/systemStatus'
receiveSubscribeRequest:
action: receive
channel:
$ref: '#/channels/currencyExchange'
reply:
channel:
$ref: '#/channels/currencyExchange'
messages:
- $ref: '#/components/messages/subscriptionStatus'
unsubscribe:
action: send
- $ref: '#/components/messages/dummyCurrencyInfo'
messages:
- $ref: '#/components/messages/subscribe'
receiveUnsubscribeRequest:
action: receive
channel:
$ref: '#/channels/currencyExchange'
reply:
channel:
$ref: '#/channels/currencyExchange'
messages:
- $ref: '#/components/messages/subscriptionStatus'
messages:
- $ref: '#/components/messages/unsubscribe'


components:
messages:
dummyCurrencyInfo:
summary: Dummy message with no real life details
description: It is here in this example to showcase that there is an additional message that normally is of a complex structure. It represents actually currency exchange value to show a reply to operation receiveSubscribeRequest with more than one possible message.
payload:
type: object
properties:
event:
type: string
const: currencyInfo
reqid:
$ref: '#/components/schemas/reqid'
data:
type: object
required:
- event
correlationId:
location: '$message.payload#/reqid'

ping:
summary: Ping server to determine whether connection is alive
description: Client can ping server to determine whether connection is alive, server responds with pong. This is an application level ping as opposed to default ping in websockets standard which is server initiated
payload:
$ref: '#/components/schemas/ping'
correlationId:
location: $message.payload#/reqid
location: '$message.payload#/reqid'

pong:
summary: Pong is a response to ping message
description: Server pong response to a ping to determine whether connection is alive. This is an application level pong as opposed to default pong in websockets standard which is sent by client in response to a ping
payload:
$ref: '#/components/schemas/pong'
correlationId:
location: $message.payload#/reqid
location: '$message.payload#/reqid'

subscribe:
description: Subscribe to a topic on a single or multiple currency pairs.
payload:
$ref: '#/components/schemas/subscribe'
correlationId:
location: $message.payload#/reqid
location: '$message.payload#/reqid'
unsubscribe:
description: Unsubscribe, can specify a channelID or multiple currency pairs.
payload:
$ref: '#/components/schemas/unsubscribe'
correlationId:
location: $message.payload#/reqid
location: '$message.payload#/reqid'
subscriptionStatus:
description: Subscription status response to subscribe, unsubscribe or exchange initiated unsubscribe.
payload:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,57 +42,79 @@ channels:
systemStatus:
$ref: '#/components/messages/systemStatus'

subscriptionStatus:
currencyInfo:
address: /
messages:
subscriptionStatus:
$ref: '#/components/messages/subscriptionStatus'
dummyCurrencyInfo:
$ref: '#/components/messages/dummyCurrencyInfo'

subscribe:
address: /
messages:
subscribe:
$ref: '#/components/messages/subscribe'

unsubscribe:
address: /
messages:
unsubscribe:
$ref: '#/components/messages/unsubscribe'


operations:
pingPong:
action: send
receivePing:
action: receive
channel:
$ref: '#/channels/ping'
reply:
channel:
$ref: '#/channels/pong'
heartbeat:
action: receive
action: send
channel:
$ref: '#/channels/heartbeat'
systemStatus:
action: receive
action: send
channel:
$ref: '#/channels/systemStatus'
subscribe:
action: send
action: receive
channel:
$ref: '#/channels/subscribe'
reply:
channel:
$ref: '#/channels/subscriptionStatus'
$ref: '#/channels/currencyInfo'
unsubscribe:
action: send
action: receive
channel:
$ref: '#/channels/unsubscribe'
reply:
channel:
$ref: '#/channels/subscriptionStatus'
$ref: '#/channels/currencyInfo'
messages:
- $ref: '#/components/messages/subscriptionStatus'


components:
messages:
dummyCurrencyInfo:
summary: Dummy message with no real life details
description: It is here in this example to showcase that there is an additional message that normally is of a complex structure. It represents actually currency exchange value to show a reply to operation receiveSubscribeRequest with more than one possible message.
payload:
type: object
properties:
event:
type: string
const: currencyInfo
reqid:
$ref: '#/components/schemas/reqid'
data:
type: object
required:
- event
correlationId:
location: '$message.payload#/reqid'
ping:
summary: Ping server to determine whether connection is alive
description: Client can ping server to determine whether connection is alive, server responds with pong. This is an application level ping as opposed to default ping in websockets standard which is server initiated
Expand Down
Loading
Loading