Comparision to OpenApi from Microsoft

[bielu]

Hey @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.

[bielu]

@VisualBean I am setting up now ci/cd so as soon you release version I will aim to release update of my package. Btw the new repo link is here:
https://github.com/bielu/Bielu.AspNetCore.AsyncApi
the docs are in progress, i need also write test coverage but yeah generally I should have something ready by eod

[bielu]

@VisualBean found another edge case, in v2 scheme, when you generate you skipping empty array of channels, however the spec is strict about existance of property even if empty array 🤦, i can ignore this error in my integration testing however might worth fix it?

[VisualBean]

@VisualBean found another edge case, in v2 scheme, when you generate you skipping empty array of channels, however the spec is strict about existance of property even if empty array 🤦, i can ignore this error in my integration testing however might worth fix it?

Good find!
It used to be like this, not sure why I ended up changing it, but I'll add it to the list of things to look at 👍

[bielu]

@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.

[bielu]

@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]

@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.

[VisualBean]

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

[VisualBean]

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

[bielu]

@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. :)

[bielu]

@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)

[bielu]

@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).

[bielu]

@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 :)

[VisualBean]

Thats great!

[bielu]

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?