基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)
艾三元 人气:1前言
回顾上一篇文章《使用Swagger做Api文档 》，文中介绍了在.net core 3.1中，利用Swagger轻量级框架，如何引入程序包，配置服务，注册中间件，一步一步的实现，最终实现生产自动生产API接口说明文档。文中结尾也留下了一个让大家思考的问题。在这里，我们重新回顾一下这几个问题
开始
一、为接口方法添加注释
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();
});
}
五、隐藏某些接口
如果不想显示某些接口，直接在controller 上，或者action 上，增加特性
[ApiExplorerSettings(IgnoreApi = true)]
六、忽视Swagger注释警告
启用 XML 注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息 例如，以下消息指示违反警告代码 1591：
原来是swagger把一些 action 方法都通过xml文件配置了，如果你不想每一个方法都这么加注释，可以这么配置，在当前项目进行配置，可以忽略警告，记得在后边加上分号 ;1591
常见错误
在Swagger使用的时候报错，无法看到列表，这里说下如何调试和主要问题：
1.找不到文件
请在浏览器 =》 F12 ==》 console 控制台 ==》点击错误信息地址
发现 是404 ，说明是找不到指定的文件，可以存在以下情况：
这是因为接口json文档定义和调用不是一个
1、定义：
ConfigureServices 方法中的 services.AddSwaggerGen 注册的一个名字 c.SwaggerDoc("v1",
2、调用：
Configure 方法中的 app.UseSwaggerUI(c => 调用 c.SwaggerEndpoint("/swagger/V1/swagger.json；
看看两者是否一致
2. 500错误无法解析
直接链接http://localhost:xxxxx/swagger/v1/swagger.json，就能看到错误了
这种可以存在以下情况：
1 . 接口请求的方式不明确： 少了[httpget]、[httpPost] 等，导致无法解析
总结
1. 通过这一篇的整体学习，我们已经解决了上一篇文章留下的问题，也知道了怎样更好的使用Swagger进行开发接口文档，更加方便快捷的使用
2. 从上篇的引用配置启动，到这一篇的升级改造，让接口文档更加通俗易懂。
3. 关注公众号可以获取资料
下载源码
加载全部内容