前言

回顾上一篇文章《使用Swagger做Api文档》，文中介绍了在.net core 3.1中，利用Swagger轻量级框架，如何引入程序包，配置服务，注册中间件，一步一步的实现，最终实现生产自动生产API接口说明文档。文中结尾也留下了一个让大家思考的问题。在这里，我们重新回顾一下这几个问题

1. 已经有接口了，但如何添加注释呢？

2. 作为接口使用者，我们关心的是接口的返回内容和响应类型，那我们如何定义描述响应类型呢？

3. 在项目开发中，使用的实体类，又如何在Swagger中展示呢？

4. 在部署项目，引用Swagger既有文档又不需要额外部署，但是如何在开发环境中使用，而在生产环境中禁用呢？

开始

一、为接口方法添加注释

1 . 按照下图所示连点三次 / 即可添加文档注释

如下所示

2.启用XML 注释

右键web 项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个,如下图所示

3.配置服务

在之前注册的Swagger服务代码中，添加以下几行代码，引入xml文件

var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）               //var basePath = AppContext.BaseDirectory;var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//这个就是刚刚配置的xml文件名               // c.IncludeXmlComments(xmlPath);//默认的第二个参数是false,对方法的注释 c.IncludeXmlComments(xmlPath,true); // 这个是controller的注释

整体的代码如下：

public void ConfigureServices(IServiceCollection services)        {            services.AddSwaggerGen(c =>{                c.SwaggerDoc("V1", new OpenApiInfo                {                    Version = "V1",   //版本 Title = $"XUnit.Core 接口文档-NetCore3.1",  //标题Description = $"XUnit.Core Http API v1",    //描述Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },                      License = new OpenApiLicense { Name = "艾三元许可证", Url = new Uri("http://i3yuan.cnblogs.com") }                });var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）               //var basePath = AppContext.BaseDirectory;var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//这个就是刚刚配置的xml文件名c.IncludeXmlComments(xmlPath);//默认的第二个参数是false,对方法的注释// c.IncludeXmlComments(xmlPath,true); //这个是controller的注释            });            services.AddControllers();        }

4.重新编译运行

查看效果

注意：如果需要对控制器进行注释说明如下，可以将

c.IncludeXmlComments(xmlPath,true); 这个设置为true,显示效果如下：

二、描述响应类型

接口使用者最关心的就是接口的返回内容和相应类型啦。下面展示一下201和400一个简单例子：

我们需要在我们的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)]

然后添加相应的状态说明：<response code="201">返回value字符串</response><response code="400">如果id为空</response>

最终代码应该是这个样子：

/// <summary>/// values带id参数的get/// </summary>/// <param name="id"></param>/// <response code="201">返回value字符串</response>/// <response code="400">如果id为空</response>  /// <returns></returns>[HttpGet("{id}")]        [ProducesResponseType(201)]        [ProducesResponseType(400)]public string Get(int id)        {return "value";        }

效果如下：

三、实体类展示添加注释

新建一个Movie的实体类，MovieModel

/// <summary>/// 这是电影实体类/// </summary>public class MovieModel    {/// <summary>/// Id/// </summary>public int Id { get; set; }/// <summary>/// 影片名称/// </summary>public string Name { get; set; }/// <summary>/// 类型/// </summary>public string Type { get; set; }    }

在控制器中引入接口方法

/// <summary>/// post方式提交电影名称/// </summary>/// <param name="movie"></param>        [HttpPost]public async Task<string> Post(MovieModel movie)        {return movie.Name;        }

效果如下：

四、在生产环境中禁用

可以将Swagger的UI页面配置在Configure的开发环境之中

放到if(env.IsDevelopment())即可。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)        {if (env.IsDevelopment())            {                app.UseDeveloperExceptionPage();#region Swagger 只在开发环节中使用app.UseSwagger();                app.UseSwaggerUI(c => {                    c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"XUnit.Core V1");                    c.RoutePrefix = string.Empty;     //如果是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的                                                      //路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件                                                      // c.RoutePrefix = "swagger"; // 如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "swagger"; 则访问路径为 根域名/swagger/index.html                });#endregion}            app.UseRouting();            app.UseAuthorization();            app.UseEndpoints(endpoints =>{                endpoints.MapControllers();            });        }