AsyncAPI Initiative Status Update (week 39, 2020) | AsyncAPI Initiative for event-driven APIs

Circular References Supported in HTML and Markdown Templates

After recent efforts into circular references support in the AsyncAPI JavaScript Parser, now we started using these features in HTML and Markdown docs generators. With the latest releases of those two templates, you can generate documentation for schemas containing circular references. Below you can see an example specification file and how its payload and payload generated example looks like in generated HTML. You can also give it a try on your own in our Playground.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
asyncapi: 2.0.0
info:
  title: Example
  version: 0.1.1
channels:
  recursive:
    subscribe:
      message:
        payload:
          $ref: '#/components/schemas/Recursive'
components:
  schemas:
    Recursive:
      type: object
      properties:
        children:
          type: array
          items:
            $ref: '#/components/schemas/Recursive'
        something:
          type: string

AsyncAPI schema with a circular reference.

Generate HTML Docs into a Single File

Thanks to the contribution from Gordeev Artem, you can now generate HTML documentation into a single file. Like what?

To generate HTML documentation for AsyncAPI files, you can use our HTML generator template. It generates an index.html file with correctly rendered content of the AsyncAPI file. In addition, it also references additional files necessary for nice display of the HTML, JavaScript, and CSS files.

From time to time, the community asked that it would be nice if the template could generate only one index.html file with all the JavaScript and CSS inline inside the HTML file.

Now it is possible! There is a new parameter added to the template called singlePage. Just pass it for example, in the CLI like this -p singlePage=true.

Parser with More Helpers and Better API docs

We released Parser release candidate 5 with features you want to have in a library before you announce the 1.0.0 release. Thanks to generous support from our community member Maciej Urbanczyk, this release candidate contains the following additions:

Missing externalDocs field in AsyncAPIDocument model
New functions to all models that need it: hasBindings, bindingProtocols, hasBinding(name), binding(name), extensionKeys, extKeys, hasExtension, hasExt, tagNames, tag, hasTag, hasDescription
Much better API documentation. In the past, it was not only missing functions that were not available but also functions that were not documented because of the wrong usage of JSDocs. Now see on your own how significant is the change by looking just on the list of functions available for ChannelParameter model:

Hacktoberfest Preparation

Hacktoberfest is a great event for people to start contributing to open source. It runs throughout October, and we want AsyncAPI Initiative to join the event. Why?

Enable different communities to jump into the AsyncAPI projects with simple tasks, so they can get familiar with what we have, where to find things, and how easy it is to kick off with the first contribution
Show to the community something that might not be so obvious, that the AsyncAPI Initiative is not only working on the specification but also a lot of great tools to make it easy to work with the specification

If you are interested in how we plan to join the Hacktoberfest, look at our plan.

The Highlight of Interesting Discussions

WAMP Protocol Bindings

There are community efforts to define bindings for Web Application Messaging Protocol (WAMP). In case you are experienced with the protocol, please join and support here.

Go Code Generation

There are community efforts to create a template for generating Go code using the AsyncAPI generator. The initial pull request is opened. You can help even if you are not familiar with AsyncAPI, as you can help with just the review of the generated code. Please join and support here.

AsyncAPI Special Interest Group (SIG) open meeting

The last meeting took place on Tuesday, 15th of September, 4PM UTC. Meeting notes and recording are available here.

The next meeting is scheduled for next Tuesday, 29th of September, 8AM UTC.

We work on the agenda for the next meeting here. At the moment, there is nothing in the agenda so you can sneak in your topic easily.

We host the meeting on Zoom. Do not forget about future meetings and always have up to date invitations in your calendar by adding your email to this mailing list.

Cover photo by Neil Thomas on Unsplash

On this page