AsyncAPI support

[carlosgil]

Hello.
Do you have plans to support the creation of AsyncAPIs (https://www.asyncapi.com/)?
Many thanks - Carlos Gil

[Radu]

Hi Carlos,

I'm afraid I'm not familiar with this, can you elaborate on what kind of support you would like to see in Oxygen XML Editor for this?

Regards,
Radu

[carlosgil]

Hello Radu,
AsyncAPI is analogous to OpenAPI (https://www.oxygenxml.com/doc/versions/ ... ework.html), but for asynchronous communications.

The tool should allow to:
- create new documents based on the spec, including things like referencing JSON schemas, in text and visual mode.
- support things like references to external schema registries, which are supported by the spec
- validate that the documents are compliant with the spec
- generate the documentation similarly to the OpenAPI

Does it make sense?

Many thanks - Carlos

[florin_nica]

Hi Carlos,

Thank you very much for your detailed proposal. I added an issue related to this on our internal issue tracker, in order to do an in-depth analysis of AsyncAPI specification, and how can we integrate it in Oxygen. I will keep you up to date with its status.

In the meantime, you can already use Oxygen to validate that the AsyncAPI documents are compliant with the spec. Whether you use YAML or JSON format for the documents, you can directly associate one of the spec JSON Schemas (https://github.com/asyncapi/spec-json-s ... er/schemas) and the validation will start. You can find more details about schema association at https://www.oxygenxml.com/doc/versions/ ... n-doc.html.

Regards,
Florin

[carlosgil]

Hello Florin,
I don't think there is a schema to associate it, so I cannot validate those asyncAPIs.
There are external tools to do that (https://www.asyncapi.com/docs/community/tooling), but it would be good that your tools does it directly, like what is done with the OpenAPI documents.
Many thanks for your feedback.
Best regards, Carlos Gil

[florin_nica]

Hi Carlos,

I tried this schema: https://raw.githubusercontent.com/async ... 2.3.0.json. It is the most recent release of the AsyncAPI spec schema. I associated it to an AsyncAPI document (you can also save it to your local machine), and the validation started automatically. This is how my sample document looks like, having a remote schema associated:

Code: Select all

---
$schema: https://raw.githubusercontent.com/asyncapi/spec-json-schemas/master/schemas/2.3.0.json
asyncapi: 2.0.0
info:
  title: Email Service
  version: '1.0.0'
  description: |
    Sends emails upon certain events
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

You can also use the Validate with... action from Validation drop-down menu on the toolbar or the Document > Validate menu.

Regards,
Florin

[carlosgil]

Hi Florin,
Thanks for that.
I've tried but it's not really working for me, I get an error: #/$schema: extraneous key [$schema] is not permitted

-----------------
$schema: https://raw.githubusercontent.com/async ... 2.3.0.json
asyncapi: 2.3.0
info:
-----------------

If I remove the $, I don't get that error but I can put anything, like "blabla" below, and it validates, so this is not really working.
And there is no code completion feature either.
Do you have any information if asyncAPI will be supported in the future, and by when?
Many thanks.

-----------------
schema: https://raw.githubusercontent.com/async ... 2.3.0.json
asyncapi: 2.3.0
info:
description: 'Real-time vehicle information: usage, safety and consumption events.'
title: Event API Product:Vehicle Partner
x-view: provider
version: v1.0.0
x-origin:
vendor: solace
name: apim-connector
components:
blabla:
parameters:
-----------------

[artur_bozieac]

Hi Carlos,

It seems that AsyncAPI specification doesn't allow $schema key.

If you want continuous validation on your AsyncAPI doc a validation scenario will be useful.
You can see how to configure it here https://www.oxygenxml.com/doc/versions/ ... nario.html.

We will consider to add AsyncAPI support in further versions, I'm afraid I cannot tell when it will be available.

Best Regards,
Artur

[carlosgil]

Hello Artur,
Coming back to this topic, we need a tool that supports:
- OAS
- JSON Schema and schema registry
- AsyncAPI.

We'll not use your tool in a general way (floating licenses) for the team until we have support for the above from a single tool.
I'll use it only for myself using a subscription model while searching for tools with that support. Whenever you have more information about your roadmaps, I'd appreciate to know the details.
Many thanks and best regards,
Carlos Gil

Architect - Integration Competence Center (ICC)
F. Hoffmann-La Roche AG / Pharma Informatics

[artur_bozieac]

Hello Carlos,

We released some new OpenAPI tools, you can see them here.
Also, we have a solid JSON Schema Support, more about this you can find on following link.

As per my last comment, we'll consider to add AsyncAPI support in further versions.
Best Regards,
Artur

[adamretter]

I would also like to request AsyncAPI support. We are embarking on a large API project here where we may use AsyncAPI, and I fear that the AsyncAPI web-based studio will not be up to the job of modelling hundreds of API services. At least it is not easy to use for large documents as it lacks auto-suggest of possible element/property names etc.

[tavy]

Hello,

In Oxygen XML Editor/Developer 25.0 we added support to edit and validate AsyncAPI documents.
https://www.oxygenxml.com/xml_editor/wh ... PI_JSON-LD

The following support is available for AsyncAPI:
- create new AsyncAPI documents based on built-in file templates (that can be customized)
- validate AsyncAPI documents accordingly to the specification
- content completion support based on the AsyncAPI JSON Schema
- edit in Text and Author mode

You can find more details in our user manual:
https://www.oxygenxml.com/doc/versions/ ... ework.html

Best Regards,
Octavian

[adamretter]

Wooohoo thanks Octavian - I am very excited to try it out in the next few days

[carlosgil]

Hello,
Any update in the roadmap for AsyncAPI?
In particular, I'd like to know if you'll be supporting version 3.x in the near future.
Many thanks in advance.
Carlos

[florin_nica]

Hi Carlos,

We plan to introduce the AsyncAPI version 3.x support in a future release of Oxygen Editor. Meanwhile, you can configure a custom validation scenario using the using the AsyncAPI 3.0 schema available in the official specification repository. This allows you to benefit from validation and content completion features. I have tested this schema and it seems to work fine: https://raw.githubusercontent.com/async ... %24id.json

Additionally, you may want to try our new product called Oxygen JSON Editor, which includes the current AsyncAPI support: https://www.oxygenxml.com/oxygen_json_editor.html
For a detailed comparison between our products, you can refer to the feature matrix available here: https://www.oxygenxml.com/xml_editor/fe ... atrix.html

Regards,
Florin