Swagger

• How to set up Swashbuckle vs Microsoft.AspNetCore.Mvc.Versioning 1
• SwaggerUI authorization
  • Adding Basic Authorization for Swagger-UI 2 2017-03-18
  • Customize Authentication Header in SwaggerUI using Swashbuckle 3 June 2015
  • HitBTC API 2.1.0 4
  • Adding Basic Authorization for Swagger-UI 5 jul 15
  • Adding a Authorization field to the Swagger UI 6 jan 16
  • Web API with OAUTH using Swagger / Swashbuckle 7
  • Swagger and ASP.NET Web API - Part II: Enabling OAuth 2.0 8
• Swagger UI - Adding multiple custom header parameters 9
• Generating Swagger example requests 10 & responses 11 with Swashbuckle
• ASP.NET Web API Help Pages using Swagger 12
• Add JWT Bearer Authorization to Swagger and ASP.NET Core 13 Oct17
• AddFileParamTypes operation filter 14 for file upload
• Modify Swagger with Request Context 15
• Annotations 16 enrich operation, response and parameter metadata
• Extend Generator with Operation, Schema & Document Filters 17
• Custom operation filters: AssignOperationVendor 18, RemoveVersionParameters 19, FormDataOperationFilter 20
• Custom UI 21 website project

Recipes

• packages

<PackageReference Include="Swashbuckle" Version="5.5.3" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="1.0.0" />

• configure swagger middleware
  • ConfigureServices permalink 22, bearer authorization ConfigureSwaggerGen.Bearer.cs 23
  • Configure link 24
  • operation filter SwaggerApiOperationIdFilter.cs 25
  • header parameter 26
• test swagger definitions

public class SwaggerTests
{
    private const string TargetUrl = "/swagger/v1.0/swagger.json";

    [Fact, IsWarmUp]
    public async Task VerifySwaggerEndpoint()
    {
        string swaggerResult;
        using (var client = new System.Net.WebClient())
        {
            swaggerResult = await client.DownloadStringTaskAsync($"{Settings.Instance.SiteURL}{TargetUrl}");
        }

        swaggerResult.Should().NotBeNull();

        var obj = JsonConvert.DeserializeObject<JObject>(swaggerResult);
        var paths = obj["paths"];
        Assert.True(paths.Children().Count() > 1);
    }
}

• better name generation UI
  • Instead of [ProducesResponseType((int)HttpStatusCode.BadRequest, Type = typeof(void))] use [SwaggerResponse(StatusCodes.Status401Unauthorized, null, "Unauthorized")].
  • Instead of [Action("name")] use SwaggerOperation("Ping", Schemes = new[] { "http" })].

OpenAPI Specification

Source of truth is YML / JSON OAS

Swagger editor (Petstore v2) 27
Swagger Petstore 2.0 28

.NET Core

Swashbuckle.AspNetCore.SwaggerUI
SwaggerEndpoint
IApplicationBuilder.UseOpenApiSwagger
app.UseSwaggerUI(c => c.SwaggerEndpoint(x, "title"))
x: /local yml or json in www root
default is /swagger/v1/swagger.json

.NET Framework 4.0 (Swashbuckle.Core 5.6.0)

SwaggerConfig.cs
HttpConfiguration.EnableSwagger
CustomProvider and/or RootUrl

Swashbuckle.Core 29 — not updated since Oct 2016
Swashbuckle.WebApi ISwaggerProvider search 30

Swagger repositories at GitHub 31

SwaggerConfig sample — all possible options .NET 4 32
CachingSwaggerProvider 33
SwaggerUiHandler 34
SwaggerDocsHandler 35
SwaggerGenerator (official) 36
HttpConfigurationExtensions (OWIN) 37
ISwaggerProvider 38

Contract-First Development

API/contract first — OpenAPI-Driven API Design

Contract first OpenAPI development (but still use Swagger UI with ASP.NET Core) 39

Code Generation

Swagger Codegen — generate server stubs and client SDKs from OpenAPI specifications 40

NSwag

Get started with NSwag and ASP.NET Core 41

Documentation

Enriched Web API Documentation using Swagger/OpenAPI in ASP.NET Core 42

OpenAPI Tooling

OpenAPITools/openapi-generator — generate API client libraries, server stubs, documentation from OpenAPI specs 43
microsoft/OpenAPI.NET — OpenAPI SDK for .NET: object model, serializers for JSON and YAML 44

dotnet-openapi

dotnet-openapi global tool 45
Microsoft.dotnet-openapi tool 46
.NET OpenAPI tool command reference v8 47, v9 48

OpenAPI Document Generation

Generate OpenAPI documents — .NET 8 49, ASP.NET Core 9 50
Generate OpenAPI specification at build time 51
Generate ASP.NET Core OpenAPI Spec at Build Time 52
Add automatic OpenAPI client code generation to .NET 6 apps 53
Using OpenAPI Auto-Generated Clients in ASP.NET Core 54
Auto-Regenerating API Client for Your OpenAPI Project 55

<

«