Swashbuckle.aspnetcore: Support Open API v3

[SimonTouchtech]

As you probably are aware of, a new version of the OpenAPI specification is being released in the end of July. I couldn't find an issue tracking introducing support for the new version in Swashbuckle, so I created this one.

Swagger-UI have not completed their support for v3, but the work is tracked at https://github.com/swagger-api/swagger-ui/issues/3083.

[sebitsi]

@domaindrivendev
Hi, any plans ? Roadmap ?

[tdesmet]

So are there any plans to support or implement this?

A good start might be https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

[x2764tech]

@tdesmet There's a nice overview of moving one schema to the other at: https://dev.to/mikeralphson/comparing-openapiswagger-20-and-300-rc1

However, this doesn't address adding features like links or the additional of OIDC as an authentication provider.

The other tripping hazard for people using SwashBuckle might be the use of adoption of CommonMark rather than GFM for documentation. Looking at the code for handling XmlComments, it translates <see cref="..."/> and <c>constants</c>, but everthing else is dumped verbatim (including any other markup).

[ChristianSauer]

We would be interested as well :)

[gaui]

Swagger-UI has completed their support for v3, would love this in Swashbuckle.

[kierenj]

Am also enjoying the SwaggerUI3 package/preview in Swashbuckle.AspNetCore, but ran up against the lack of JWT bearer auth, http security scheme type [in OpenAPI 2.0]. Currently creating APIs which use JWTs but not OAuth. Just curious - is this one on the roadmap? Not pushing for it, but making plans!

[x2764tech]

This is on the roadmap for ASPNET Core 2.1 - http://miroslavpopovic.com/posts/2018/02/upcoming-http-api-related-changes-in-aspnet-core-2.1.

[kierenj]

Ah, great - although what's they say 'currently we only have runtime generation' - is that built in to ASP.NET Core? They're just referring to Swashbuckle with the royal 'we'?

[dennisroche]

@kierenj AFAIK Swashbuckle is still required for OpenApi document generation. The improvements being made in ASP.NET Core are to generate better ApiExplorer metadata that is then used by Swashbuckle.

[RainingNight]

OAI v3 is great, It'll be so exciting.

[kierenj]

I may have missed a subtlety here - is anyone aware if whether OpenAPI 3 generation is planned for Swashbuckle then? It would be quite bold to say the least if the .NET team announce runtime gen on the roadmap when that assumes someone else is going to do the work?

[sandorfr]

@kierenj no one is. Asp .net core team is just improving api explorer so other third party library can get more accurate information without attribute soup. This has nothing to do with OpenAPI 3 per say. In addition I don't see any evidence that someone has started working on Swashbuckle support for OpenApi v3

[darrelmiller]

Sorry, I did look for an existing issue before creating a new one, but apparently I failed.

So, I have made reasonable progress bringing the OpenAPI.NET library into Swashbuckle. I have created fork off the .netstandard2.0 branch. The main projects are compiling now with the OpenApiDocument as a replacement for SwaggerDocument. I still have to fix a bunch of compiler errors in the tests. It's mostly mechanical syntax changes.

The biggest challenges in getting it all working will be

• translating between produces/consumes and the new content object
• Converting body parameters to RequestBody objects.

But once I find a few more hours to work on it, I should have something I can push up for folks to try out.

[reyx]

@darrelmiller How can i help you to finish this task?

[darrelmiller]

Hey @reyx The branch is here https://github.com/darrelmiller/Swashbuckle.AspNetCore/tree/dm/openapiv3 I was held up because I needed to update the OpenAPI.NET library to allow reading fragments so that I could read in Schema Objects independently. I just updated the branch to use the new library. The job now is to get all the tests passing again. There are still a whole lot to do.

I have had other deadlines that have prevented me from working on it recently. I'm hoping that changes this week.

[RaulRG]

Moving from SwaggerDocument to OpenApiDocument Looks like the right thing to do. OpenAPI.NET Looks terrific and an Integration with this project would be very welcome. Any ideas about a timeline? I read Milestone 4.0, but I don't know the Roadmap.

[darrelmiller]

@RaulRG I will make time to get this done over the next two weeks.

[darrelmiller]

Down from 65 failing tests to 20. Slow but steady progress.

[RaulRG]

Great news @darrelmiller ! Thank you very much for your efforts

[darrelmiller]

All the tests passing except the 6 integration tests. Hopefully that's just because I'm emitting V3 and the validator is trying to validate v2.

[domaindrivendev]

@darrelmiller - thanks for all the hard work, much appreciated! Before I release this, there's several other changes that I'd like to get out before I update the ASP.NET Core lower bound to 2.0. These are all captured in the 3.0.0 milestone which is fairly close to completion. Once that's done, I'll merge in the ASP.NET Core / netstandard2.0 upgrade, followed by your branch (this merge is likely to be a little hairy). I've targeted those changes in the 4.0.0 milestone. So, there'll be two major version increments of Swashbuckle in relatively quick session to adhere to semver.

To summarize next steps:

1. Wrap up the 3.0.0 milestone
2. Merge the netstandard2.0 branch into master
3. Merge your branch into master
4. Wrap up the 4.0.0 milestone (incl. OAI V3 support)

Does this make sense?

[darrelmiller]

@domaindrivendev Well, I'm sure there is still a bunch of stuff that I will need to fix, so you have time to get your next steps done before I'll be ready to merge. But the steps to get there seem sound to me.

[davidbirchwork]

any news on a timeline for the 3.0.0 milestone? the work in the thread looks great.

[darrelmiller]

I have been struggling to merge with all the changes in the master. I am hoping to have time next week as it is our "Fix, Hack, Learn" week at Microsoft :-D

[RainingNight]

Exciting!

[Havunen]

Does OAI3 support include all the features described in the standard ? Im mostly interested about links https://swagger.io/docs/specification/links/

Is there any documentation available how these could be used so the generator understands them?

[binaryPUNCH]

Any news regarding the progress on this?

[domaindrivendev]

I’m working on this now and hope to make a beta package available early next week

[darrelmiller]

@domaindrivendev Next time I am in Seattle we should get together and beers are on me.

[domaindrivendev]

Beta version now available, leveraging OpenAPI.NET object model, with full support for OpenAPI 3.0 specification …

https://www.nuget.org/packages/Swashbuckle.AspNetCore/5.0.0-beta

[jzbuaa]

any plan to release the beta version?

[mluker]

• Asp.Net 2.2
• Swashbuckle v5.0.0 rc2

I am also experiencing an issue with OAS 3 and using IFormFile as a parameter.

This is my endpoint:
public async Task<object> UploadTest(IFormFile file) { }

When using OAS 3 nswag will generate the above endpoint's 'IFileFormat' parameter as a 'Blob' within the client code.
sample(body?: Blob | undefined): Observable<ObjectCommonApiResponse>;

When using OAS 2 nswag will generate the above endpoint's 'IFileFormat' parameter as a 'FileParameter' within the client code.
sample(file?: FileParameter | null | undefined): Observable<ObjectCommonApiResponse>;

Maybe I am missing something but I am not sure how to turn my file into 'Blob' so I can pass it into the service. On the other hand, when it's a 'FileParameter' type, using OAS 2, I can just extend the 'FileParameter' interface with my own class and send that in and it works as expected.