[Tools] Swagger

[fffej]

We use Swagger to document some of our web APIs.

I believe it should be in Adopt.

[fffej]

@Michael-Upton Am I right in thinking that the out of process work is using this? Any reason why it shouldn't be in adopt?

[ChrisHurley]

A subtle nuance here - there's the OpenAPI specification (backed by Swagger) and there's OpenAPI/Swagger generation libraries like Swashbuckle. Are we referring to both?

(Also worth noting that if you really want your generated documentation to be useful you need to be using the correct attributes and XML doc strings - otherwise you'll end up with a relatively bare list of endpoints).

[fffej]

Good point, let's say we adopt the Open API spec and our default tool of choice is ?

[tugberkugurlu]

FWIW, we currently use NSwag for reasons described here:

• It seemed to be maintained more actively than Swashbuckle at the time (still seems to be the case, last commit is from 3 hours ago). Not sure what Swashbuckle's current state is though.
• They are in process of getting Open API 3.0 support out (still seems to be ongoing: Epic: Support OpenApi 3 RicoSuter/NSwag#945).
• This doesn't have the problem we have hit on https://github.com/red-gate/SQLEstateManager-vNext/pull/150 related to ASP.NET Core integration.

[ChrisHurley]

NSwag looks pretty good to me, and I wasn't aware of its existence - although I'm interested in where things are with API versioning support, since we use that with WebApi now, and their WebApi support is deprecated.

(Maybe we should look into retiring WebApi in favour of ASP.NET Core...)

[tugberkugurlu]

(Maybe we should look into retiring WebApi in favour of ASP.NET Core...)

👍 as there will be less and less support for Web API as time progresses.

[tugberkugurlu]

NSwag has docs on official docs section, too: https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-2.1&tabs=visual-studio%2Cvisual-studio-xml

[PeterGerrard]

For reference Swashbuckle also has these docs:
https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.1&tabs=visual-studio

[fffej]

To try and get this one closed out here's where I think we are.

Adopt:

• Open API specification - our APIs are built using the Open API specification

Explore

• NSwag - An implementation of the Open API specification currently being explored by the Data Catalog team.
• Swashbuckle - An implementation of the OpenAPI specification currently being explored by the Versioning teams for providing the out-of-process APIs.

👍 if you're happy and I'll create a PR.