• Skip to primary navigation
  • Skip to content
  • Skip to primary sidebar
  • Skip to footer

Fran Méndez

Personal website

  • Home
  • AsyncAPI
  • Blog
  • About
  • Contact

Docgen now supports AsyncAPI 1.1.0 (and more!)

AsyncAPI specification, AsyncAPI tooling · April 8, 2018

I just published asyncapi-docgen 1.10.1 🎉

This version includes some new cool features:

  1. Support for allOf, anyOf, and oneOf on schemas.
  2. Support for oneOf on topic operations.
  3. Support for topic parameters.
  4. Auto-generated code samples for messages and schemas.

1. Support for allOf, anyOf, and oneOf

From now on, if your spec is using one of these keywords, the library will know how to render them. Let’s see some examples.

allOf

YAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
components:
  schemas:
    mammal:
      type: object
        title: Mammal
        properties:
          canBreath:
            type: boolean
          legCount:
            type: number
    dog:
      allOf:
        - $ref: '#/components/schemas/mammal'
        - type: object
            title: Dog
            properties:
              canBark:
                type: boolean
                enum:
                  - true

anyOf

YAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
components:
  schemas:
    user:
      type: object
      title: User
      required:
        - id
        - username
      properties:
        id:
          description: User Id
          $ref: "#/components/schemas/id"
        full_name:
          description: User full name
          type: string
        username:
          $ref: "#/components/schemas/username"
          
    superuser:
      type: object
      title: Superuser
      properties:
        isSuperUser:
          type: boolean
          default: true
          enum:
             - true
    
    signup:
      type: object
      required:
        - method
        - datetime
      properties:
        user:
          anyOf:
            - $ref: '#/components/schemas/user'
            - $ref: '#/components/schemas/superuser'
        method:
          description: Signup method
          type: string
          enum:
            - email
            - facebook
            - twitter
            - github
            - google
        datetime:
          $ref: "#/components/schemas/datetime"

oneOf

YAML
1
2
3
4
5
6
7
8
9
10
11
12
13
components:
  schemas:
    user:
      type: object
      title: User
      properties:
        idOrEmail:
          oneOf:
            - type: number
              description: User Id
            - type: string
              description: User email
              format: email

2. Support for oneOf on topic operations

You can now specify that a topic supports many messages:

YAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
asyncapi: "1.1.0"
info:
  title: AsyncAPI Sample
  version: "1.0.0"
 
topics:
  single.topic.for.all.messages:
    subscribe:
      oneOf:
        - $ref: '#/components/messages/heartbeat'
        - $ref: '#/components/messages/signup'
 
components:
  messages:
    heartbeat:
      payload:
        type: object
        required:
          - type
        properties:
          type:
            type: string
            enum:
              - heartbeat
    signup:
      payload:
        type: object
        required:
          - type
        properties:
          type:
            type: string
            enum:
              - signup
          email:
            type: string
            format: email

3. Support for topic parameters

You can now document topic parameters:

YAML
1
2
3
4
5
6
7
topics:
  event.{streetlightId}.lighting.measured:
    parameters:
      - name: streetlightId
        description: The ID of the streetlight.
        schema:
          type: string

4. Auto-generated code samples for messages and schemas

If you look at the examples above, you’ll see that many of them contain auto-generated examples. These examples will only appear if an example is not provided in the asyncapi file.

Get notified about new AsyncAPI releases!


And that’s it for now!

Do you want to have new features? Feel free to open an issue, or even better, make a Pull Request! 🚀

Until next time! 👋

Filed Under: AsyncAPI specification, AsyncAPI tooling

Fran Méndez

APIs & Integrations Engineer at New Relic. Former Lead Engineer at Hitch. Creator of the AsyncAPI specification.

« Announcing AsyncAPI 1.1.0
AsyncAPI 1.2.0 is out now! »

Reader Interactions

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Primary Sidebar

Newsletter

Recent Posts

  • Thoughts on the Atlassian App Week 2018 (Portland)
  • AsyncAPI 1.2.0 is out now!
  • Docgen now supports AsyncAPI 1.1.0 (and more!)
  • Announcing AsyncAPI 1.1.0
  • Nordic APIs Tooling Review: AsyncAPI

Newsletter

Footer

  • Github
  • Linkedin
  • Twitter

Copyright © 2021 · Fran Méndez