ASP.NET Core 2.2 系列【三】集成Swagger

swagger

是一款自动生成在线接口文档+功能测试功能软件

一、安装程序包

通过管理 nuget 程序包安装，搜索swashbuckle.aspnetcore

二、配置 swagger

将 swagger 添加到 startup.configureservices 方法中的服务集合中：

1 //注入swagger服务
2 services.addswaggergen(c =>
3 {
4     c.swaggerdoc("v1", new info { title = "my api", version = "v1" });
5 });

在 startup.configure 方法中，启用中间件为生成的 json 文档和 swagger ui 提供服务

1 //启用swagger服务
2 app.useswagger();
3 app.useswaggerui(c =>
4 {
5     c.swaggerendpoint("/swagger/v1/swagger.json", "my api v1");
6     c.defaultmodelsexpanddepth(-1); //设置为 - 1 可不显示models
7     c.docexpansion(docexpansion.none);//设置为none可折叠所有方法
8 });

运行项目，可在 http://localhost:<port>/swagger 浏览 api文档，如下所示：

如果想把swagger作为启动页面，可修改launchsettings.json，把  launchurl设置为  swagger：

1 "iis express": {
2     "commandname": "iisexpress",
3     "launchbrowser": true, //是否在浏览器中启动
4     "launchurl": "swagger", //在浏览器中启动的相对url
5     "environmentvariables": { //将环境变量设置为键/值对
6       "aspnetcore_environment": "development"
7     }
8   }

所有的controller 的方法都是可以在 ui 上面进行测试。点击方法可以展开对应的区域，点击【try it out】→ 【输入参数】→ 点击【execute】。

三、可扩展性

swagger 文档信息和描述

修改addswaggergen 方法，用来添加文档信息。例如：作者，版权，描述。

 1 services.addswaggergen(options =>
 2 {
 3     options.swaggerdoc("v1",
 4         new info
 5          {
 6             version = "v1",
 7             title = "在线接口文档",
 8             description = "一个简单的例子",
 9             contact = new contact { name = "tenghao", email = "[e-mail]" },
10             license = new license { name = "tenghao", url = "https://www.cnblogs.com/tenghao510/" }
11  });
12 });

下图展示了 swagger ui 显示添加的版本信息。

xml注释

【右键项目】→【属性】→ 【生成】→ 【勾选xml 文档文件】注意自己的路径

修改addswaggergen 方法。

备注：includexmlcomments方法中的includexmlcomments参数控制是否显示控制器注释，默认是false。

 1 //注入swagger服务
 2 services.addswaggergen(options =>
 3 {
 4     options.swaggerdoc("v1",
 5         new info
 6         {
 7             version = "v1",
 8             title = "在线接口文档",
 9             description = "一个简单的例子",
10             contact = new contact { name = "tenghao", email = "[e-mail]" },
11             license = new license { name = "tenghao", url = "https://www.cnblogs.com/tenghao510/" }
12         });
13 
14     // 为 swagger json and ui设置xml文档注释路径
15     var basepath = path.getdirectoryname(typeof(program).assembly.location);//获取应用程序所在目录
16     var xmlpath01 = path.combine(basepath, "netcorewebapi.xml"); 
17     options.includexmlcomments(xmlpath01, true);
18     var xmlpath = path.combine(basepath, "netcorewebapi.model.xml"); 
19     options.includexmlcomments(xmlpath);
20 });

运行项目，再看看效果：