1 user/signedup:
2  subscribe:
3    $ref: "#/components/messages/userSignUp"

1 {
2   "field" : [...]
3 }

1 {
2  "id": "urn:com:smartylighting:streetlights:server"
3 }

id: 'urn:com:smartylighting:streetlights:server'

1 {
2  "id": "https://github.com/smartylighting/streetlights-server"
3 }

id: 'https://github.com/smartylighting/streetlights-server'

1 {
2  "title": "AsyncAPI Sample App",
3  "description": "This is a sample server.",
4  "termsOfService": "http://asyncapi.org/terms/",
5  "contact": {
6    "name": "API Support",
7    "url": "http://www.asyncapi.org/support",
8    "email": "support@asyncapi.org"
9  },
10  "license": {
11    "name": "Apache 2.0",
12    "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
13  },
14  "version": "1.0.1"
15 }

1 title: AsyncAPI Sample App
2 description: This is a sample server.
3 termsOfService: http://asyncapi.org/terms/
4 contact:
5  name: API Support
6  url: http://www.asyncapi.org/support
7  email: support@asyncapi.org
8 license:
9  name: Apache 2.0
10  url: http://www.apache.org/licenses/LICENSE-2.0.html
11 version: 1.0.1

1 {
2  "name": "API Support",
3  "url": "http://www.example.com/support",
4  "email": "support@example.com"
5 }

1 name: API Support
2 url: http://www.example.com/support
3 email: support@example.com

1 {
2  "name": "Apache 2.0",
3  "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
4 }

1 name: Apache 2.0
2 url: http://www.apache.org/licenses/LICENSE-2.0.html

1 {
2  "production": {
3    "url": "development.gigantic-server.com",
4    "description": "Development server",
5    "protocol": "kafka",
6    "protocolVersion": "1.0.0"
7  }
8 }

1 production:
2  url: development.gigantic-server.com
3  description: Development server
4  protocol: kafka
5  protocolVersion: '1.0.0'

1 {
2  "url": "development.gigantic-server.com",
3  "description": "Development server",
4  "protocol": "kafka",
5  "protocolVersion": "1.0.0"
6 }

1 url: development.gigantic-server.com
2 description: Development server
3 protocol: kafka
4 protocolVersion: '1.0.0'

1 {
2  "servers": {
3    "development": {
4      "url": "development.gigantic-server.com",
5      "description": "Development server",
6      "protocol": "amqp",
7      "protocolVersion": "0.9.1"
8    },
9    "staging": {
10      "url": "staging.gigantic-server.com",
11      "description": "Staging server",
12      "protocol": "amqp",
13      "protocolVersion": "0.9.1"
14    },
15    "production": {
16      "url": "api.gigantic-server.com",
17      "description": "Production server",
18      "protocol": "amqp",
19      "protocolVersion": "0.9.1"
20    }
21  }
22 }

1 servers:
2  development:
3    url: development.gigantic-server.com
4    description: Development server
5    protocol: amqp
6    protocolVersion: 0.9.1
7  staging:
8    url: staging.gigantic-server.com
9    description: Staging server
10    protocol: amqp
11    protocolVersion: 0.9.1
12  production:
13    url: api.gigantic-server.com
14    description: Production server
15    protocol: amqp
16    protocolVersion: 0.9.1

1 {
2  "servers": [
3    {
4      "url": "{username}.gigantic-server.com:{port}/{basePath}",
5      "description": "The production API server",
6      "protocol": "secure-mqtt",
7      "variables": {
8        "username": {
9          "default": "demo",
10          "description": "This value is assigned by the service provider, in  this example `gigantic-server.com`"
11        },
12        "port": {
13          "enum": [
14            "8883",
15            "8884"
16          ],
17          "default": "8883"
18        },
19        "basePath": {
20          "default": "v2"
21        }
22      }
23    }
24   ]
25 }

1 servers:
2 - url: '{username}.gigantic-server.com:{port}/{basePath}'
3  description: The production API server
4  protocol: secure-mqtt
5  variables:
6    username:
7      # note! no enum here means it is an open value
8      default: demo
9      description: This value is assigned by the service provider, in this  example `gigantic-server.com`
10    port:
11      enum:
12        - '8883'
13        - '8884'
14      default: '8883'
15    basePath:
16      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
17      default: v2

1 {
2  "defaultContentType": "application/json"
3 }

defaultContentType: application/json

1 {
2  "user/signedup": {
3    "subscribe": {
4      "$ref": "#/components/messages/userSignedUp"
5    }
6  }
7 }

1 user/signedup:
2  subscribe:
3    $ref: "#/components/messages/userSignedUp"

1 {
2  "description": "This channel is used to exchange messages about users signing up",
3  "subscribe": {
4    "summary": "A user signed up.",
5    "message": {
6      "description": "A longer description of the message",
7      "payload": {
8        "type": "object",
9        "properties": {
10          "user": {
11            "$ref": "#/components/schemas/user"
12          },
13          "signup": {
14            "$ref": "#/components/schemas/signup"
15          }
16        }
17      }
18    }
19  },
20  "bindings": {
21    "amqp": {
22      "is": "queue",
23      "queue": {
24        "exclusive": true
25      }
26    }
27  }
28 }

1 description: This channel is used to exchange messages about users signing up
2 subscribe:
3  summary: A user signed up.
4  message:
5    description: A longer description of the message
6    payload:
7      type: object
8      properties:
9        user:
10          $ref: "#/components/schemas/user"
11        signup:
12 bindings:
13  amqp:
14    is: queue
15    queue:
16      exclusive: true

1 {
2  "subscribe": {
3    "message": {
4      "oneOf": [
5        { "$ref": "#/components/messages/signup" },
6        { "$ref": "#/components/messages/login" }
7      ]
8    }
9  }
10 }

1 subscribe:
2  message:
3    oneOf:
4      - $ref: '#/components/messages/signup'
5      - $ref: '#/components/messages/login'

1 {
2  "operationId": "registerUser",
3  "summary": "Action to sign a user up.",
4  "description": "A longer description",
5  "tags": [
6    { "name": "user" },
7    { "name": "signup" },
8    { "name": "register" }
9  ],
10  "message": {
11    "headers": {
12      "type": "object",
13      "properties": {
14        "applicationInstanceId": {
15          "description": "Unique identifier for a given instance of the publishing application",
16          "type": "string"
17        }
18      }
19    },
20    "payload": {
21      "type": "object",
22      "properties": {
23        "user": {
24          "$ref": "#/components/schemas/userCreate"
25        },
26        "signup": {
27          "$ref": "#/components/schemas/signup"
28        }
29      }
30    }
31  },
32  "bindings": {
33    "amqp": {
34      "ack": false
35    },
36  },
37  "traits": [
38    { "$ref": "#/components/operationTraits/kafka" }
39  ]
40 }

1 operationId: registerUser
2 summary: Action to sign a user up.
3 description: A longer description
4 tags:
5  - name: user
6  - name: signup
7  - name: register
8 message:
9  headers:
10    type: object
11    properties:
12      applicationInstanceId:
13        description: Unique identifier for a given instance of the publishing application
14        type: string
15  payload:
16    type: object
17    properties:
18      user:
19        $ref: "#/components/schemas/userCreate"
20      signup:
21        $ref: "#/components/schemas/signup"
22 bindings:
23  amqp:
24    ack: false
25 traits:
26  - $ref: "#/components/operationTraits/kafka"

1 {
2  "bindings": {
3    "amqp": {
4      "ack": false
5    }
6  }
7 }

1 bindings:
2  amqp:
3    ack: false

1 {
2  "user/{userId}/signup": {
3    "parameters": {
4      "userId": {
5        "description": "Id of the user.",
6        "schema": {
7          "type": "string"
8        }
9      }
10    },
11    "subscribe": {
12      "$ref": "#/components/messages/userSignedUp"
13    }
14  }
15 }

1 user/{userId}/signup:
2  parameters:
3    userId:
4      description: Id of the user.
5      schema:
6        type: string
7  subscribe:
8    $ref: "#/components/messages/userSignedUp"

1 {
2  "user/{userId}/signup": {
3    "parameters": {
4      "userId": {
5        "description": "Id of the user.",
6        "schema": {
7          "type": "string"
8        },
9        "location": "$message.payload#/user/id"
10      }
11    },
12    "subscribe": {
13      "$ref": "#/components/messages/userSignedUp"
14    }
15  }
16 }

1 user/{userId}/signup:
2  parameters:
3    userId:
4      description: Id of the user.
5      schema:
6        type: string
7      location: $message.payload#/user/id
8  subscribe:
9    $ref: "#/components/messages/userSignedUp"

1 {
2  "name": "UserSignup",
3  "title": "User signup",
4  "summary": "Action to sign a user up.",
5  "description": "A longer description",
6  "contentType": "application/json",
7  "tags": [
8    { "name": "user" },
9    { "name": "signup" },
10    { "name": "register" }
11  ],
12  "headers": {
13    "type": "object",
14    "properties": {
15      "correlationId": {
16        "description": "Correlation ID set by application",
17        "type": "string"
18      },
19      "applicationInstanceId": {
20        "description": "Unique identifier for a given instance of the publishing application",
21        "type": "string"
22      }
23    }
24  },
25  "payload": {
26    "type": "object",
27    "properties": {
28      "user": {
29        "$ref": "#/components/schemas/userCreate"
30      },
31      "signup": {
32        "$ref": "#/components/schemas/signup"
33      }
34    }
35  },
36  "correlationId": {
37    "description": "Default Correlation ID",
38    "location": "$message.header#/correlationId"
39  },
40  "traits": [
41    { "$ref": "#/components/messageTraits/commonHeaders" }
42  ]
43 }

1 name: UserSignup
2 title: User signup
3 summary: Action to sign a user up.
4 description: A longer description
5 contentType: application/json
6 tags:
7  - name: user
8  - name: signup
9  - name: register
10 headers:
11  type: object
12  properties:
13    correlationId:
14      description: Correlation ID set by application
15      type: string
16    applicationInstanceId:
17      description: Unique identifier for a given instance of the publishing application
18      type: string
19 payload:
20  type: object
21  properties:
22    user:
23      $ref: "#/components/schemas/userCreate"
24    signup:
25      $ref: "#/components/schemas/signup"
26 correlationId:
27  description: Default Correlation ID
28  location: $message.header#/correlationId
29 traits:
30  - $ref: "#/components/messageTraits/commonHeaders"

1 {
2  "name": "UserSignup",
3  "title": "User signup",
4  "summary": "Action to sign a user up.",
5  "description": "A longer description",
6  "tags": [
7    { "name": "user" },
8    { "name": "signup" },
9    { "name": "register" }
10  ],
11  "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
12  "payload": {
13    "$ref": "path/to/user-create.avsc#/UserCreate"
14  }
15 }

1 name: UserSignup
2 title: User signup
3 summary: Action to sign a user up.
4 description: A longer description
5 tags:
6  - name: user
7  - name: signup
8  - name: register
9 schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0'
10 payload:
11  $ref: 'path/to/user-create.avsc/#UserCreate'

1 {
2  "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
3  "contentType": "application/json"
4 }

1 schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0'
2 contentType: application/json

1 {
2    "name": "user",
3    "description": "User-related messages"
4 }

1 name: user
2 description: User-related messages

1 {
2  "description": "Find more info here",
3  "url": "https://example.com"
4 }

1 description: Find more info here
2 url: https://example.com

1 {
2  "$ref": "#/components/schemas/Pet"
3 }

  $ref: '#/components/schemas/Pet'

1 User
2 User_1
3 User_Name
4 user-name
5 my.org.User

1 "components": {
2  "schemas": {
3    "Category": {
4      "type": "object",
5      "properties": {
6        "id": {
7          "type": "integer",
8          "format": "int64"
9        },
10        "name": {
11          "type": "string"
12        }
13      }
14    },
15    "Tag": {
16      "type": "object",
17      "properties": {
18        "id": {
19          "type": "integer",
20          "format": "int64"
21        },
22        "name": {
23          "type": "string"
24        }
25      }
26    }
27  },
28  "messages": {
29    "userSignUp": {
30      "summary": "Action to sign a user up.",
31      "description": "Multiline description of what this action does.\nHere you have another line.\n",
32      "tags": [
33        {
34          "name": "user"
35        },
36        {
37          "name": "signup"
38        }
39      ],
40      "headers": {
41        "type": "object",
42        "properties": {
43          "applicationInstanceId": {
44            "description": "Unique identifier for a given instance of the publishing application",
45            "type": "string"
46          }
47        }
48      },
49      "payload": {
50        "type": "object",
51        "properties": {
52          "user": {
53            "$ref": "#/components/schemas/userCreate"
54          },
55          "signup": {
56            "$ref": "#/components/schemas/signup"
57          }
58        }
59      }
60    }
61  },
62  "parameters": {
63    "userId": {
64      "name": "userId",
65      "description": "Id of the user.",
66      "schema": {
67        "type": "string"
68      }
69    }
70  },
71  "correlationIds": {
72    "default": {
73      "description": "Default Correlation ID",
74      "location": "$message.header#/correlationId"
75    }
76  },
77  "messageTraits": {
78    "commonHeaders": {
79      "headers": {
80        "type": "object",
81        "properties": {
82          "my-app-header": {
83            "type": "integer",
84            "minimum": 0,
85            "maximum": 100
86          }
87        }
88      }
89    }
90  }
91 }

1 components:
2  schemas:
3    Category:
4      type: object
5      properties:
6        id:
7          type: integer
8          format: int64
9        name:
10          type: string
11    Tag:
12      type: object
13      properties:
14        id:
15          type: integer
16          format: int64
17        name:
18          type: string
19  messages:
20    userSignUp:
21      summary: Action to sign a user up.
22      description: |
23        Multiline description of what this action does.
24        Here you have another line.
25      tags:
26        - name: user
27        - name: signup
28      headers:
29        type: object
30        properties:
31          applicationInstanceId:
32            description: Unique identifier for a given instance of the publishing application
33            type: string
34      payload:
35        type: object
36        properties:
37          user:
38            $ref: "#/components/schemas/userCreate"
39          signup:
40            $ref: "#/components/schemas/signup"
41  parameters:
42    userId:
43    - name: userId
44      description: Id of the user.
45      schema:
46        type: string
47  correlationIds:
48    default:
49      description: Default Correlation ID
50      location: $message.header#/correlationId
51  messageTraits:
52    commonHeaders:
53      headers:
54        type: object
55        properties:
56          my-app-header:
57            type: integer
58            minimum: 0
59            maximum: 100

1 {
2  "type": "string",
3  "format": "email"
4 }

1 type: string
2 format: email

1 {
2  "type": "object",
3  "required": [
4    "name"
5  ],
6  "properties": {
7    "name": {
8      "type": "string"
9    },
10    "address": {
11      "$ref": "#/components/schemas/Address"
12    },
13    "age": {
14      "type": "integer",
15      "format": "int32",
16      "minimum": 0
17    }
18  }
19 }

1 type: object
2 required:
3 - name
4 properties:
5  name:
6    type: string
7  address:
8    $ref: '#/components/schemas/Address'
9  age:
10    type: integer
11    format: int32
12    minimum: 0

1 {
2  "type": "object",
3  "additionalProperties": {
4    "type": "string"
5  }
6 }

1 type: object
2 additionalProperties:
3   type: string

1 {
2  "type": "object",
3  "additionalProperties": {
4    "$ref": "#/components/schemas/ComplexModel"
5  }
6 }

1 type: object
2 additionalProperties:
3  $ref: '#/components/schemas/ComplexModel'

1 {
2  "type": "object",
3  "properties": {
4    "id": {
5      "type": "integer",
6      "format": "int64"
7    },
8    "name": {
9      "type": "string"
10    }
11  },
12  "required": [
13    "name"
14  ],
15  "example": {
16    "name": "Puma",
17    "id": 1
18  }
19 }

1 type: object
2 properties:
3  id:
4    type: integer
5    format: int64
6  name:
7    type: string
8 required:
9 - name
10 example:
11  name: Puma
12  id: 1

1 {
2  "schemas": {
3    "ErrorModel": {
4      "type": "object",
5      "required": [
6        "message",
7        "code"
8      ],
9      "properties": {
10        "message": {
11          "type": "string"
12        },
13        "code": {
14          "type": "integer",
15          "minimum": 100,
16          "maximum": 600
17        }
18      }
19    },
20    "ExtendedErrorModel": {
21      "allOf": [
22        {
23          "$ref": "#/components/schemas/ErrorModel"
24        },
25        {
26          "type": "object",
27          "required": [
28            "rootCause"
29          ],
30          "properties": {
31            "rootCause": {
32              "type": "string"
33            }
34          }
35        }
36      ]
37    }
38  }
39 }

1 schemas:
2  ErrorModel:
3    type: object
4    required:
5    - message
6    - code
7    properties:
8      message:
9        type: string
10      code:
11        type: integer
12        minimum: 100
13        maximum: 600
14  ExtendedErrorModel:
15    allOf:
16    - $ref: '#/components/schemas/ErrorModel'
17    - type: object
18      required:
19      - rootCause
20      properties:
21        rootCause:
22          type: string

1 {
2  "schemas": {
3    "Pet": {
4      "type": "object",
5      "discriminator": "petType",
6      "properties": {
7        "name": {
8          "type": "string"
9        },
10        "petType": {
11          "type": "string"
12        }
13      },
14      "required": [
15        "name",
16        "petType"
17      ]
18    },
19    "Cat": {
20      "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
21      "allOf": [
22        {
23          "$ref": "#/components/schemas/Pet"
24        },
25        {
26          "type": "object",
27          "properties": {
28            "huntingSkill": {
29              "type": "string",
30              "description": "The measured skill for hunting",
31              "enum": [
32                "clueless",
33                "lazy",
34                "adventurous",
35                "aggressive"
36              ]
37            }
38          },
39          "required": [
40            "huntingSkill"
41          ]
42        }
43      ]
44    },
45    "Dog": {
46      "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
47      "allOf": [
48        {
49          "$ref": "#/components/schemas/Pet"
50        },
51        {
52          "type": "object",
53          "properties": {
54            "packSize": {
55              "type": "integer",
56              "format": "int32",
57              "description": "the size of the pack the dog is from",
58              "minimum": 0
59            }
60          },
61          "required": [
62            "packSize"
63          ]
64        }
65      ]
66    }
67  }
68 }

1 schemas:
2  Pet:
3    type: object
4    discriminator: petType
5    properties:
6      name:
7        type: string
8      petType:
9        type: string
10    required:
11    - name
12    - petType
13  Cat:  ## "Cat" will be used as the discriminator value
14    description: A representation of a cat
15    allOf:
16    - $ref: '#/components/schemas/Pet'
17    - type: object
18      properties:
19        huntingSkill:
20          type: string
21          description: The measured skill for hunting
22          enum:
23          - clueless
24          - lazy
25          - adventurous
26          - aggressive
27      required:
28      - huntingSkill
29  Dog:  ## "Dog" will be used as the discriminator value
30    description: A representation of a dog
31    allOf:
32    - $ref: '#/components/schemas/Pet'
33    - type: object
34      properties:
35        packSize:
36          type: integer
37          format: int32
38          description: the size of the pack the dog is from
39          minimum: 0
40      required:
41      - packSize

1 {
2  "type": "userPassword"
3 }

type: userPassword

1 {
2  "type": "apiKey",
3  "in": "user"
4 }

1 type: apiKey,
2 in: user

1 {
2   "type": "X509"
3 }

type: X509

1 {
2  "type": "symmetricEncryption"
3 }

type: symmetricEncryption

1 {
2  "type": "http",
3  "scheme": "basic"
4 }

1 type: http
2 scheme: basic

1 {
2  "type": "httpApiKey",
3  "name": "api_key",
4  "in": "header"
5 }

1 type: httpApiKey
2 name: api_key
3 in: header

1 {
2  "type": "http",
3  "scheme": "bearer",
4  "bearerFormat": "JWT",
5 }

1 type: http
2 scheme: bearer
3 bearerFormat: JWT

1 {
2  "type": "oauth2",
3  "flows": {
4    "implicit": {
5      "authorizationUrl": "https://example.com/api/oauth/dialog",
6      "scopes": {
7        "write:pets": "modify pets in your account",
8        "read:pets": "read your pets"
9      }
10    }
11  }
12 }

1 type: oauth2
2 flows:
3  implicit:
4    authorizationUrl: https://example.com/api/oauth/dialog
5    scopes:
6      write:pets: modify pets in your account
7      read:pets: read your pets

1 {
2  "type": "oauth2",
3  "flows": {
4    "implicit": {
5      "authorizationUrl": "https://example.com/api/oauth/dialog",
6      "scopes": {
7        "write:pets": "modify pets in your account",
8        "read:pets": "read your pets"
9      }
10    },
11    "authorizationCode": {
12      "authorizationUrl": "https://example.com/api/oauth/dialog",
13      "tokenUrl": "https://example.com/api/oauth/token",
14      "scopes": {
15        "write:pets": "modify pets in your account",
16        "read:pets": "read your pets"
17      }
18    }
19  }
20 }

1 type: oauth2
2 flows:
3  implicit:
4    authorizationUrl: https://example.com/api/oauth/dialog
5    scopes:
6      write:pets: modify pets in your account
7      read:pets: read your pets
8  authorizationCode:
9    authorizationUrl: https://example.com/api/oauth/dialog
10    tokenUrl: https://example.com/api/oauth/token
11    scopes:
12      write:pets: modify pets in your account
13      read:pets: read your pets

1
2
3
{
  "user_pass": []
}

user_pass: []

1
2
3
{
  "api_key": []
}

api_key: []

1 {
2  "petstore_auth": [
3    "write:pets",
4    "read:pets"
5  ]
6 }

1 petstore_auth:
2 - write:pets
3 - read:pets

1 {
2  "description": "Default Correlation ID",
3  "location": "$message.header#/correlationId"
4 }

1 description: Default Correlation ID
2 location: $message.header#/correlationId

1      expression = ( "$message" "." source )
2      source = ( header-reference | payload-reference )
3      header-reference = "header." ["#" fragment]
4      payload-reference = "payload." ["#" fragment]
5      fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901)