Add IDocumentProvider service and its implementation (2)

[RicoSuter]

• Add IDocumentProvider as done in this PR: Add IDocumentProvider service and its implementation #1658
• Add ISwaggerGenerator to NSwag.SwaggerGeneration (OpenApiDocumentSettings no longer used, less code)
  • AspNetCoreToSwaggerGenerator implements ISwaggerGenerator and thus can be added to the SwaggerDocumentRegistry
• Split UseSwaggerUiWithApiExplorer() into two methods UseSwagger() and UseSwaggerUi()
  • We have to break the API anyway so this is to make it more SRP
• Prepare everything so that the WebApiToSwaggerGenerator dependency can eventually be removed

Question:

• Do the the documents be in DI or can't we just add them to the registry which is in DI?

Simple config:

    public void ConfigureServices(IServiceCollection services)
    {
        ...

        // Add NSwag OpenAPI/Swagger DI services and configure documents
        services.AddSwagger(options =>
            options.AddDocument(settings => settings.SchemaType = SchemaType.OpenApi3));
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...
        // Add middlewares to service the OpenAPI/Swagger document and the web UI
        app.UseSwagger();
        app.UseSwaggerUi3();
    }

Advanced config:

    public void ConfigureServices(IServiceCollection services)
    {
        …

        // Add OpenAPI and Swagger DI services and configure documents

        // Adds the NSwag services
        services.AddSwagger(options => options
            // Register a Swagger 2.0 document generator
            .AddDocument("swagger", settings =>
            {
                // Add custom document processors, etc.
                settings.DocumentProcessors.Add(new SecurityDefinitionAppender("TEST_HEADER", new SwaggerSecurityScheme
                {
                    Type = SwaggerSecuritySchemeType.ApiKey,
                    Name = "TEST_HEADER",
                    In = SwaggerSecurityApiKeyLocation.Header,
                    Description = "TEST_HEADER"
                }));
            })
            // Register an OpenAPI 3.0 document generator
            .AddDocument("openapi", settings => settings.SchemaType = SchemaType.OpenApi3));
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...

        // Add OpenAPI and Swagger middlewares to serve documents and web UIs

        // Add Swagger 2.0 document serving middleware
        app.UseSwagger("swagger", options => options.Path = "/swagger/v1/swagger.json");

        // Add web UIs to interact with the document
        app.UseSwaggerUi3(options =>
        {
            // Define OpenAPI/Swagger document route (defined with UseSwaggerWithApiExplorer)
            options.SwaggerRoute = "/swagger/v1/swagger.json";

            // Define web UI route
            options.SwaggerUiRoute = "/swagger_ui";
        });
        app.UseSwaggerReDoc(options =>
        {
            options.SwaggerRoute = "/swagger/v1/swagger.json";
            options.SwaggerUiRoute = "/swagger_redoc";
        });

        // Add OpenAPI 3.0 document serving middleware
        app.UseSwagger("openapi", options => options.Path = "/openapi/v1/openapi.json");

        // Add web UIs to interact with the document
        app.UseSwaggerUi3(options =>
        {
            options.SwaggerRoute = "/openapi/v1/openapi.json";
            options.SwaggerUiRoute = "/openapi_ui";
        });
        app.UseSwaggerReDoc(options =>
        {
            options.SwaggerRoute = "/openapi/v1/openapi.json";
            options.SwaggerUiRoute = "/openapi_redoc";
        });

        // Add Swagger UI with multiple documents
        app.UseSwaggerUi3(options =>
        {
            // Add multiple OpenAPI/Swagger documents to the Swagger UI 3 web frontend
            options.SwaggerRoutes.Add(new SwaggerUi3Route("Swagger", "/swagger/v1/swagger.json"));
            options.SwaggerRoutes.Add(new SwaggerUi3Route("Openapi", "/openapi/v1/openapi.json"));
            options.SwaggerRoutes.Add(new SwaggerUi3Route("Petstore", "http://petstore.swagger.io/v2/swagger.json"));

            // Define web UI route
            options.SwaggerUiRoute = "/swagger_all";
        });
    }