https://github.com/RSuter/NSwag/wiki#ways-to-use-the-toolchain

Customizations

Swagger generation:

You can customize the Swagger generator with the following extension points of NSwag:

Document Processors and Operation Processors

https://github.com/RSuter/NSwag/wiki/OWIN-Middleware

Package: NSwag.AspNet.Owin (.NET 4.5+)

The NuGet package provides extension methods to register the NSwag ASP.NET OWIN middlewares:

The middlewares are based on WebApiToSwaggerGenerator - the old reflection based ASP.NET Core and ASP.NET generator

Swagger only:

app.UseSwagger(assembly, configure): Registers the Swagger generator on a given route

Swagger and Swagger UI: (用了这个，就不能用上面的，是冲突的)

app.UseSwaggerUi(assembly, configure): Registers the Swagger generator and Swagger UI v2.x on the given routes
app.UseSwaggerUi(configure): Registers only the Swagger UI on the given route
app.UseSwaggerUi3(configure): Registers the Swagger generator and Swagger UI v3.x on the given routes
app.UseSwaggerReDoc(configure): Registers the Swagger generator and ReDoc on the given routes

The default routes to access the Swagger specification or Swagger UI:

Swagger JSON: http://yourserver/swagger/v1/swagger.json
Swagger UI: http://yourserver/swagger

1. Install required NuGet packages

First, you need to install the required NSwag NuGet packages.

2. Register the middleware

OWIN Startup Class Detection

public class Startup

{

    public void Configuration(IAppBuilder app)

    {

        var config = new HttpConfiguration();

        app.UseSwaggerUi(typeof(Startup).Assembly, settings =>

        {

            // configure settings here

            // settings.GeneratorSettings.*: Generator settings and extension points

            // settings.*: Routing and UI settings

        });

        app.UseWebApi(config);

        config.MapHttpAttributeRoutes();

        config.EnsureInitialized();

    }

}

Configure the routing of the Swagger requests

There are two ways to do this:

自定义

Post process the served Swagger specification

It is possible to transform the generated Swagger specification before it is served to the client:

app.UseSwagger(typeof(Startup).Assembly, settings =>

{

    settings.PostProcess = document =>

    {

        document.Info.Description = "My description";

    };

});

If you want to implement more reusable code, you can also implement Document Processors and Operation Processors.

UseSwagger和UseSwaggerUi3只能用一个

app.UseSwaggerUi3(typeof(Startup).Assembly, settings =>

            {

                // configure settings here

                // settings.GeneratorSettings.*: Generator settings and extension points

                // settings.*: Routing and UI settings

                settings.GeneratorSettings.DefaultUrlTemplate = "api/{controller}/{action}/{id}";

                settings.PostProcess = document =>

                {

                    document.Info.Title = "My Services";

                    document.Info.Version = "1.5";

                    document.Info.Contact = new SwaggerContact {Name = "My team", Email = "test@qq.com" };

                };

            });

参考

https://github.com/RSuter/NSwag/blob/master/src/NSwag.Sample.NETCore22/Startup.cs 这里有ConfigureServices的方法签名示例

https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-2.2&tabs=visual-studio%2Cvisual-studio-xml#customize-api-documentation 这里有如何进行文档自定义的代码

https://docs.particular.net/samples/dependency-injection/aspnetcore/ 需要引用Autofac.Extensions.DependencyInjection

https://github.com/RSuter/NSwag/wiki/Middlewares 两种不同的middleware

https://github.com/RSuter/NSwag/wiki/AspNetCore-Middleware 这个里面是用ConfigureServices来处理文档

https://github.com/RSuter/NSwag/wiki/OWIN-Middleware 这个里面是用pp.UseSwaggerUi3(configure)来处理文档

巴特西

定制swagger的UI

Customizations

1. Install required NuGet packages

2. Register the middleware

自定义

Post process the served Swagger specification

参考

最新文章

热门文章