Let's start with clarifying Swagger vs OpenApi

• OpenAPI = Specification
• Swagger = Tools for implementing the specification

Versions

• Swagger ver.2 (OpenAPI 2) - Swashbuckle (.Net) v4

• OpenAPI 3 (Swagger ver.3) - Swashbuckle (.Net) v5 RC

  whats-new-in-openapi-3-0 A Visual Guide to What's New in Swagger 3.0

MSDN: Get started with Swashbuckle and ASP.NET Core

Worth to know:

• A lot of customization and extension possibilities - see Swagger Setup https://github.com/domaindrivendev/Swashbuckle.AspNetCore
• [ProducesResponseType(StatusCodes.Status..., Type = typeof(IfAnotherTypeIsReturned))]
• [Produces("application/json")] usually better set globally
• Comments for actions and DTO objects
• DataAnnotations can be used too (like required, default)
• Other comment type - 'Example'
• Enums Customizations
  • swagger Configuration DescribeAllEnumsAsStrings()
  • [JsonConverter(typeof(StringEnumConverter))]
  • [EnumMember(Value="CustomEnumStringValue")]

• Can be used by a variety of rest clients (for example Postman)
• https://swagger.io/docs/specification/2-0/basic-structure/

• Swagger-Codegen

  Run script: Tools\Invoke-SwaggerCodegen.ps1

• NSwagStudio

• and more ...

• Stoplight Prism

  Run script: Tools\Invoke-FakeBackend.ps1

• Swagmock

• and more ...

• Validators, Manifest Designers, Server Generators etc.
• https://swagger.io/tools/