swagger的使用

NuGet包 ：Swashbuckle.AspNetCore

1、设置默认直接首页访问 —— 生产环境

在Configure中配置中间件：

 

app.UseSwaggerUI(c =>

{

c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");

c.RoutePrefix = "";//路径配置，设置为空，表示直接访问该文件，

});

 

 

 

2.为接口添加注释

需要用到xml文档，右键web 项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个，当然老规矩，你也可以自己起一个名字：

 

 

导入

 var basePath = AppContext.BaseDirectory;
 var xmlPath = Path.Combine(basePath, "Blog.Core.xml")//这个就是刚刚配置的xml文件名
 c.IncludeXmlComments(xmlPath);

 

 

3、忽略注释警告

swagger把一些 action 方法都通过xml文件配置了，如果你不想每一个方法都这么加注释，可以这么配置（对当前项目进行配置，可以忽略警告，记得在后边加上分号 ;1591）：

 

 

4、给控制器也添加注释

我们上边只是给方法加了注释，但是控制器还没有加上，那怎么办呢，有一个复杂的方法，就是添加一个过滤器  c.DocumentFilter<ControllerDescriptionFilter>(); ，然后自己添加一个 .Tags ，但是这个麻烦！不多说，官方已经考虑到了这个问题了，很简单：

首先我们在控制器上加上注释：

 

 

然后配置swagger的 xml 文档导入方法：

 

5、对 Model 也添加注释说明

这里现在有两个情况，或者说是两个操作方案：

 

1、当前 api 层直接引用了Model 层；

 

这个时候，我们只需要配置仿照上边 api 层配置的xml文档那样，在 Model 层的 XML 输出到 API 层就行了：

 

 

2、API 层没有直接引用 Model 层，而是通过级联的形式；

 

 

6、导入model.xml到swagger，然后api添加参数

 #region Swagger

  

 var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath;

 var basePath2 = AppContext.BaseDirectory;

 

 services.AddSwaggerGen(c =>

 {

     c.SwaggerDoc("V1", new OpenApiInfo

     {

         // {ApiName} 定义成全局变量，方便修改

         Version = "V1",

         Title = $"{ApiName} 接口文档——Netcore 3.0",

         Description = $"{ApiName} HTTP API V1",

         Contact = new OpenApiContact { Name = ApiName, Email = "[email protected]", Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") },

         License = new OpenApiLicense { Name = ApiName, Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") }

     });

     c.OrderActionsBy(o => o.RelativePath);

 

     //就是这里！！！！！！！！！

     var xmlPath = Path.Combine(basePath, "blog.core.test3.0.xml");//这个就是刚刚配置的xml文件名

     c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改

 

 });

  #endregion

7、隐藏某些接口

如果不想显示某些接口，直接在controller 上，或者action 上，增加特性

[ApiExplorerSettings(IgnoreApi = true)]