基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)
前言
回顾上一篇文章《使用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. 关注公众号可以获取资料
上一篇: 2014在职mba排名