AsyncAPI EDA Design & Documentation ecosystem update (1 October - 31 December 2022)

asyncapi-eda-design-01-10-31-12-2022-update.md

AsyncAPI EDA Design & Documentation ecosystem update (1 October - 31 December 2022)

Update refers to repositories:

• studio
• asyncapi-react
• html-template
• markdown-template
• server-api
• generator
• cli

Note: the generator and cli update is described from an EDA design & documentation point of view. For more changes please refer to update in the EDA Development area.

studio

• New Features:

  • Studio supports validation through Spectral. Now, user has possibility to check issues (called "diagnostics") related to the AsyncAPI specification. Spectral defined issues/diagnostics in 4 groups: errors related to the invalid AsyncAPI document (cannot be disabled), warnings related to good practices which is not followed, informations which inform user about some things like using old AsyncAPI version and hints which inform about some tips. At the moment there is no possibility to add your own rule under validation (Spectral has this possibility), but it is on our roadmap in the current calendar year. In addition to improved validation, we have also redesigned the "diagnostics" terminal's tab. You can filter issues by type and text, and enable/disable validation of a given type - you can only disable warnings/informations/hints (errors are mandatory) - throught Studio's settings.

    

  • Studio now supports the tooltips in some places, like navigation. From then on, elements that will have logic after an action (such as a click) will have a tooltip describing what the action does - for better DX and UX.

    

  • We have new category in templates - tutorials. This is a category that will contain AsyncAPI documents used mainly in our tutorials - https://www.asyncapi.com/docs/tutorials

    

  • We updated all old dependencies used in Studio, so issues like Use latest version of monaco-yaml and monaco-editor or Studio do not work out of the box with new @asyncapi/specs 4.0 are fixed.

  • Using url query parameter in Studio is fixed - fix: specify source when document is from the url . From now on, Studio resolves the external resource from the point of view of the passed url, so this means that any reference used in the document is resolved from the document location.

• Opened PRs:

  • Support file-system. It is not yet a finished PR but some things are already working like validation of opened documents, using files from the system via File System Access API as well as local (from the browser - localstorage), tree-view of files etc. You can test (preview), but please be aware of changing code and bugs. Feedback is more than welcome. We do not know when this will be integrated into the Studio source-code, but the expected time is January-February 2023.

  • Switch to visualiser library. Hopefully we will merge it in upcoming weeks.

• Ideas/discussions/issues:

  • We are still discussing the Drag & Drop blocks functionality in the Studio. At the moment, support for multiple files is much more important and will allow easier implementation of the mentioned functionality. For more information, please see issuem and the other issus referencing it.

asyncapi-react

NOTE: Included changes only for next branch.

• New Features:
  • Added config option to expand/collapse the examples payload. Now, we can expand by default all payload's examples by component configuration. By default, all panels are collapsed.
• Opened PRs:
  • We wanna group Servers in sidebar navigation like Operation Objects by config option.
• Ideas/discussions/issues:
  • date-time format is not displaying in proper way in some environments. Check more info.

html-template

You can find more info about changes in the look of generated sections in the react-component section.

• New Features:
  • New parameter to enable setting favicon for rendered HTML documentation page. Thanks Rüdiger Busche!
  • New parameter to enable timeout for pdf generation. Thanks Javi!
• Opened PRs: Nothing
• Ideas/discussions/issues: Nothing

markdown-template

• New Features: Nothing
• Opened PRs:
  • We start migration template to the new ParserAPI. We wanna test new ParserJS API and check the DX of new API.
• Ideas/discussions/issues: Nothing

server-api

• New Features: Nothing
• Opened PRs:
  • We have started implementing the "share" capability for AsyncAPI documents.. We wanna add new path in server-api and then integrate that endpoint with the Studio to enable "share" option.
• Ideas/discussions/issues:
  • Deploy new version of server-api to k8s on each release. Atm, we have to deploy new version of server-api on k8s cluster each time, when new version is released. We should automate it.

generator

• New Features: Nothing
• Opened PRs:
  • New ParserJS v2 needs some fix before merge, but hopefully we will merge it in upcoming weeks. Sorry for delay!
• Ideas/discussions/issues: Nothing

cli

• New Features: Nothing
• Opened PRs:
  • Spectral integration in the CLI needs some fix before merge, but hopefully we will merge it in upcoming weeks. Sorry for delay!
• Ideas/discussions/issues: Nothing

Reminder: latest cli uses latest studio that you can open by asyncapi new --studio or asyncapi start studio.

See you in next time!