Comparision to OpenApi from Microsoft

@VisualBean

I started looking into https://github.com/asyncapi/saunter
. I’m trying to base my approach on how Microsoft’s OpenAPI generation works, so I’ve been figuring out what to use when replacing OpenAPI schema references.

The main piece I’m unsure about is how to replace OpenApiSchema:

https://github.com/microsoft/OpenAPI.NET/blob/c87204a3a9857e1d23812a3fbe55972438517c47/src/Microsoft.OpenApi/Models/OpenApiSchema.cs#L15

The closest equivalent I’ve found so far is:

https://github.com/ByteBardOrg/AsyncAPI.NET/blob/vnext/src/ByteBard.AsyncAPI/Models/JsonSchema/AsyncApiJsonSchema.cs

Am I correct in assuming this would be the right replacement?

Once I have something working, I plan to either submit a PR to Saunter or publish it as an MIT-licensed package.

Welcome to AsyncAPI.NET. Thank you for reporting your first issue. Please check out our contributors guide.

You are absolutely correct.
AsyncApiJsonSchema would be the same.

Note that there is a slight hierarchical difference in asyncapi where we technically have another type which is the MultiFormatSchema and IAsyncApiSchema.

There should be something in the wiki, otherwise let me know and I can make some docs for you 👍

@VisualBean

@VisualBean thanks for rapid answer. Yeah I am aware, i was considering to use IAsyncApiSchema but for some reason microsoft use their model instead of using either of interfaces IOpenApiExtensible, IOpenApiSchema.
will let you know if i have more question, do you want keep whole conversation in this issue or do you want me to open new issue for each question?

Yeah, I needed to introduce the interface in order to keep things type safe to the degree I wanted for the library, but it serves mostly as a marker interface.

There should be helpers (extensions) to help figure out and convert the types (particularly for the schema types)

It's fine keeping everything here for posterity.

I have questions about serialize methods:

I am assuming it is how they should be calleed, however do you plan to prepare async overloads? as it would make sense based on that we using async writer?

I have questions about serialize methods:
I am assuming it is how they should be calleed, however do you plan to prepare async overloads? as it would make sense based on that we using async writer?

Yes, definitely, but it will require a bit of work as it touches practically everything.

I done quite a progress already, need figure out some things, but generally if you interest there is my fork:
https://github.com/bielu/saunter/tree/feature/poc
for now i started with new project, however i will either move it to original project and send pr, depending on answer here:
asyncapi/saunter#244
as if they don't maintain it, there is no point of discussing it :) and i will start new repo with new generator.

I was one of the maintainers of saunter for a while. Wanted to migrate it to use asyncapi.net - but ended up not having enough time.

The original maintainer stepped back due to time constraints and other priorities (if I remember correctly), and it's now maintained by a few people - not sure how active though.

Id probably start a new thing if it was me 😅, but saunter does have a lot of gravitas in the community.

@VisualBean

@VisualBean yeah it is linked through asyncapi docs so wanted make sure people can use it, however it was not developed so 🤷

@VisualBean

@VisualBean i managed to get my version working already, I am now thinking i will release it as separate package. I am aiming to release first alpha this week. I managed to get it up this state so it is almost compliant with v3 of schema, however still working through with few annoying exceptions

v1 (2).json

Very cool!

Note that 3.1.0 has released (only very minor change to jsonschema basically) which I will update to tonight (or very soon at least).

The actual change will basically only be jsonschema (although i might need to introduce a new type for this change in order to be backwards compatible with V2) and updating the read version (string).

@VisualBean

@VisualBean i think there is small bug v3 generation, the type on

 "operationBindings": {
      "postBind": {
        "http": {
          "type": "response",
          "method": "POST"
        }
      }
    }

apparently type is not expect value 🤷 i am using this tool to validate api spec: https://asyncapi.github.io/asyncapi-react/

What is 'PostBind'? (or is this a component reference?)

OperationBindings are key (protocol) value (binding values) i.e bindings: { http: {} } if using the http binding.

I dont think the tool validates specific bindings (i also dont see 'PostBind' as an 'official' binding.)

in asyncapi.net bindings are type safe - there is a way to add custom bindings though (without having to go through adding them specifically to the library itself. https://github.com/ByteBardOrg/AsyncAPI.NET/wiki/Bindings#custom-bindings)

I just noticed that it might be a component reference - do you have a spec to reproduce the issue with?

@VisualBean

@VisualBean it comes from example for sautern, i ported same examples:

it is just Post Operation to random endpoint. However even in your HttpOperationBinding Type is required, however v3 spect does not expected type. and when i checked spec the type was depracated but not documented as removed?! https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject (the same object exist in v2)

ahhh, i see the problem now.
https://github.com/asyncapi/bindings/blob/master/http/README.md

the http binding was updated as part of the v3 work and my implementation (in the bindings project) uses the old v2 version, but at least minimally the binding version should be part of the output. preferably we need to find a way to have compatible bindings.
its a breaking change between V2 and V3 essentially, so V2 needs the type, and V3 doesn't use it.
Ill make a hotfix for this.

Removed here asyncapi/bindings@306f1fc#diff-8e568763d7d4e15f9465300afa93c121c7f8e399acfff4c2aee7e70ed1199401L36 (undocumented breaking change.)

@VisualBean

@VisualBean any update on new version :)?

@VisualBean

@VisualBean any update on new version :)?

Yeah, I'm working on it.
Took a stab at the rules, but I have to rethink the approach.

3.1.0 looks like they have 0 changes affecting the actual spec.

The http one is todo.

@VisualBean

@VisualBean is there anything what i can do to help you with updating package to 3.1 schema? :) I have some spare time on my hands :)

@VisualBean is there anything what i can do to help you with updating package to 3.1 schema? :) I have some spare time on my hands :)

Im actually almost done with it.

Rules work for v2, v3 or both.
Upgrade the version to 3.1.0 (I have no idea why they upgraded the spec version for this release. it makes no sense (only a binding was added..).
Working on figuring out a upgrade/downgrade fix for bindings.

PR's added. will let them sit for a day before i merge them in

@bielu

@bielu I've queued a beta release - please test it out 👍 ByteBard.AsyncAPI.NET.2.1.3-beta.13

@VisualBean

@VisualBean i used copilot to update package:
bielu/Bielu.AspNetCore.ApiDescriptions#6
i will need review it comments about issues and validate if they are actually issues. will do it tomorrow.
However seems like most woks as we expect. :)

@VisualBean

@VisualBean I can confirm that 3.1 generation works well, however i still have issue with v2 schema, where channels property is not generated properly

{
  "asyncapi" : "2.6.0",
  "info" : {
    "title" : "Test API",
    "version" : "1.0.0",
    "description" : "Test API for integration tests"
  },
  "servers" : {
    "test-server" : {
      "url" : "localhost:5000",
      "protocol" : "http"
    }
  },
  "channels" : { }
}

that's schema which is correct by v2 standard, however you throw error on it :)

The field 'channels' in 'document' object is REQUIRED. [#/channels]

@VisualBean

@VisualBean I can confirm that 3.1 generation works well, however i still have issue with v2 schema, where channels property is not generated properly
{
  "asyncapi" : "2.6.0",
  "info" : {
    "title" : "Test API",
    "version" : "1.0.0",
    "description" : "Test API for integration tests"
  },
  "servers" : {
    "test-server" : {
      "url" : "localhost:5000",
      "protocol" : "http"
    }
  },
  "channels" : { }
}
that's schema which is correct by v2 standard, however you throw error on it :)
The field 'channels' in 'document' object is REQUIRED. [#/channels]

From a yaml/json point of view, i would agree.
However 2.6.0 States channels are REQUIRED.

Empty channels in respect to 2.6.0 means nothing to integrate with I.e no topics to use.
Rendering the spec effectively useless to consumers.

Why it is my firm belief that channels are a hard requirement for 2.6.0 (also the individual Channel objects).

In my opinion it's an oversight and due to json conversion Logic that Empty channels are allowed in the playground.

You Can however (if you don't want the error in your lib) disable the Channel rule (override the validation rules to not include it)

@VisualBean

@VisualBean so based on their parser the object of channel is required, it can be empty however it has to exist 🤷. I can also really disable v2 validation in tests as i dont really care about v2 :)

@VisualBean

@VisualBean so based on their parser the object of channel is required, it can be empty however it has to exist 🤷. I can also really disable v2 validation in tests as i dont really care about v2 :)

Yeah. Exactly.
I believe it’s an oversight from leaning heavily on json validation basically (from their parsers side).
Which is why I implemented it as a hard requirement, but via the validators so it can be disabled.

You’ll likely notice that this lib can technically produce the same Empty channels dictionary 😅 as validations are run during reading, but not writing (if i remember correctly).

@VisualBean

@VisualBean i am building now new version, however i added note for v2:
https://github.com/bielu/Bielu.AspNetCore.AsyncApi?tab=readme-ov-file#asyncapi-2x
and adjusted my unit tests
so all good now :)

Thats great!

There is new version https://www.nuget.org/packages/Bielu.AspNetCore.AsyncApi/1.0.0-beta.639068353194068762 if you want to use it, I waiting for starting new project to start using this library, I will probably do more things then, however if you find any issue feel free to raise issue on my end. I guess we can close this discussion for now?

Navigation Menu

Repository navigation

Comparision to OpenApi from Microsoft #24

3 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Comparision to OpenApi from Microsoft #24

Description

Activity

github-actions commented on Jan 30, 2026

VisualBean commented on Jan 30, 2026

bielu commented on Jan 30, 2026

VisualBean commented on Jan 30, 2026

bielu commented on Jan 30, 2026

VisualBean commented on Jan 30, 2026

bielu commented on Jan 30, 2026

VisualBean commented on Jan 30, 2026

bielu commented on Jan 30, 2026

bielu commented on Feb 2, 2026

VisualBean commented on Feb 2, 2026

bielu commented on Feb 2, 2026

VisualBean commented on Feb 2, 2026

bielu commented on Feb 2, 2026

VisualBean commented on Feb 2, 2026

3 remaining items

bielu commented on Feb 4, 2026

VisualBean commented on Feb 4, 2026

bielu commented on Feb 11, 2026

VisualBean commented on Feb 11, 2026

VisualBean commented on Feb 11, 2026

VisualBean commented on Feb 15, 2026

bielu commented on Feb 15, 2026

bielu commented on Feb 16, 2026

VisualBean commented on Feb 16, 2026

bielu commented on Feb 16, 2026

VisualBean commented on Feb 16, 2026

bielu commented on Feb 16, 2026

VisualBean commented on Feb 16, 2026

bielu commented on Feb 16, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions