Swagger接口文档

1.Swagger介绍

Swagger工具，用于为ASP.NET Core后端接口生成漂亮的API文档，API文档是前后端开发人员联系的纽带。
本文采用Swagger版本及ASP.NET Core版本如下。

项目	版本号
Swashbuckle.AspNetCore	5.0.0-rc4
ASP.NET Core	.Net Core 2.2

2.安装Swashbuckle.AspNetCore

2.1 控制台

Install-package Swashbuckle.AspNetCore -Version 5.0.0-rc4

2.2 Nuget包管理器

3.添加Swagger服务

                //添加Swagger生成器服务
                services.AddSwaggerGen(c=> {
                //添加Swagger文档
                c.SwaggerDoc("v1",new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
            });

4.添加Swagger到中间件

                app.UseSwagger();
                app.UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");//Swagger文档路径
                    c.RoutePrefix = "";//设置为首页访问
                });

4.接口添加注释文档

1.首先生成Xml文档

2.代码中配置

               services.AddSwaggerGen(c=> {
                //添加Swagger文档
                c.SwaggerDoc("v1",new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                //
                c.CustomOperationIds(apiDesc =>
                {
                    return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;
                });
                //接口添加注释
                var filePath = Path.Combine(System.AppContext.BaseDirectory, "Swaggger5Test.xml");
                c.IncludeXmlComments(filePath);

                //Model添加注释
                var modelPath = Path.Combine(System.AppContext.BaseDirectory, "Swagger5Test.Models.xml");
                c.IncludeXmlComments(modelPath);
            });

5.添加过滤器

添加Path过滤器，可以只显示以/api/Product的控制器的文档

                //过滤器
                app.UseSwagger(c => {
                    c.PreSerializeFilters.Add((swaggerDoc, httpReq) => {
                        OpenApiPaths paths = new OpenApiPaths();
                        foreach (var path in swaggerDoc.Paths)
                        {
                            if (path.Key.StartsWith("/api/Product"))//过滤Path
                                paths.Add(path.Key, path.Value);
                        }
                        swaggerDoc.Paths = paths;
                      
                        swaggerDoc.Servers = new List { new OpenApiServer { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" } };
                    });

                });

6.设置首页访问

1.首先修改launchSettings.json文件

2.代码设置

                app.UseSwaggerUI(c =>
                {

                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");//Swagger文档路径
                    c.RoutePrefix = "";//设置为首页访问
                });

7.注意

警告如何处理：给接口添加注释之后，如果有的接口没有添加注释，就会生成警告，解决方式是在取消显示警告中添加1591；如下图：

8.源代码

Swagger5Test