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.

[github-actions]

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

[VisualBean]

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 👍

[bielu]

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

[VisualBean]

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.

[bielu]

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?

[VisualBean]

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.

[bielu]

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.

[VisualBean]

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.

[bielu]

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

[bielu]

@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

[VisualBean]

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

[bielu]

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

[VisualBean]

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?

[bielu]

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

[VisualBean]

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