秦学士和朱洁,3.19政变,婴儿身高体重标准表2013
在使用web api时，对于开发人员来说，了解其各种方法可能是一项挑战。在asp.net core上，web api 辅助工具介绍二个中间件，包括：swashbuckle和nswag .net。本篇先讲swashbuckle。二者都使用swagger规范，swagger也称为openapi，解决了为web api生成有用文档和帮助页面的问题。它提供了诸如交互式文档，客户端sdk生成和api可发现性等好处。
(1) swashbuckle.aspnetcore是一个开源项目，用于为asp.net core web api生成swagger文档。
(2) nswag是另一个开源项目，该项目将swashbuckle和autorest（客户端生成）的功能集成在一个工具链中。用于生成swagger文档并将swagger ui或redoc集成到asp.net core web api中。此外，nswag还提供了为api生成c＃和typescript客户端代码的方法。
1.1 什么是swagger / openapi
swagger是一种与开发语言无关的规范，用于描述rest api。swagger项目被捐赠给openapi计划，现在称为openapi。两个名称可互换使用; 但是，openapi是首选。它允许计算机和it人理解服务的功能，而无需直接访问实现（源代码，网络访问，文档）。一个目标是最小化连接不相关服务所需的工作量。另一个目标是减少准确记录服务所需的时间。
1.2 swagger规范（swagger.json）
swagger流程的核心是swagger规范，默认情况下是一个名为swagger.json的文档。它由swagger工具链（或其第三方实现）根据你的服务生成。它描述了 api 的功能以及使用 http 对其进行访问的方式。 它驱动 swagger ui，并由工具链用来启用发现和客户端代码生成。
1.3 swagger ui
swagger ui 提供了基于 web 的 ui，它使用生成的 swagger 规范提供有关服务的信息。 swashbuckle 和 nswag 均包含 swagger ui 的嵌入式版本，因此可使用中间件注册调用将该嵌入式版本托管在 asp.net core 应用中。
关于swashbuckle有三个主要组成部分：
(1) swashbuckle.aspnetcore.swagger： 一个swagger对象模型和中间件，用于将swaggerdocument对象公开为json端点。
(2) swashbuckle.aspnetcore.swaggergen：一个swagger生成器，可swaggerdocument直接从路由，控制器和模型构建对象。它通常与swagger端点中间件结合使用，以自动显示swagger json。
(3) swashbuckle.aspnetcore.swaggerui： swagger ui工具的嵌入式版本。它解释 swagger json 以构建描述 web api 功能的可自定义的丰富体验。它包括用于公共方法的内置测试工具。
2.1 包安装
通过vs 2017的程序包管理器控制台，运行安装install-package swashbuckle.aspnetcore -version 5.0.0-beta。 安装信息如下所示：
2.2 配置swagger中间件
将 swagger 生成器添加到 startup.configureservices 方法中的服务集合中
我要评论 //将swaggergen服务添加到服务集合中， openapiinfo是它的自带类。
services.addswaggergen(c =>
{
//注意不能用大写v1，不然老报错，not found /swagger/v1/swagger.json
c.swaggerdoc("v1", new openapiinfo { title = "my api", version = "v1" });
});
startup.configure 方法中，启用中间件为生成的 json 文档和 swagger ui 提供服务
public void configure(iapplicationbuilder app)
{
//...
// enable middleware to serve generated swagger as a json endpoint.
app.useswagger();
// enable middleware to serve swagger-ui (html, js, css, etc.),
// specifying the swagger json endpoint.
// useswaggerui方法调用启用静态文件中间件。
app.useswaggerui(c=> {
c.swaggerendpoint("/swagger/v1/swagger.json", "my api v1");
});
app.usemvc();
}
启动应用，并导航到 http://localhost:<port>/swagger/下，查看web api生成swagger文档如下所示(一个网页，二处截图拼在一起)：
swagger 提供了为对象模型进行归档和自定义 ui 以匹配你的主题的选项。
3.1 api 信息和说明的配置
可以在addswaggergen方法中配置，添加诸如作者，许可证和描述之类的信息，通过openapiinfo类来添加。
services.addswaggergen(c =>
{
//注意不能用大写v1，不然老报错，not found /swagger/v1/swagger.json
c.swaggerdoc("v1", new openapiinfo{
version = "v1",
title = "todo api",
//服务描述
description = "a simple example asp.net core web api",
//api服务条款的url
termsofservice = new uri("http://tempuri.org/terms"),
contact = new openapicontact
{
name = "joe developer",
email = "joe.developer@tempuri.org"
},
license = new openapilicense
{
name = "apache 2.0",
url = new uri("http://www.apache.org/licenses/license-2.0.html")
}
});
});
swagger ui 显示版本的信息：
3.2 xml注释api
在“解决方案资源管理器”中右键单击该项目，然后选择“编辑 <project_name>.csproj”。 手动添加以下代码到 .csproj 文件中。
<propertygroup>
<generatedocumentationfile>true</generatedocumentationfile>
<nowarn>$(nowarn);1591</nowarn>
</propertygroup>
接下来配置 swagger 以使用生成的 xml 文件。对于 linux 操作系统，文件名和路径区分大小写。例如，“todoapi.xml”文件在 windows 上有效，但在 centos 上无效。配置和解决如下所示：
services.addswaggergen(c =>
{
//...配置swaggerdoc 省略
// set the comments path for the swagger json and ui.
var xmlfile = $"{assembly.getexecutingassembly().getname().name}.xml";
var xmlpath = path.combine(appcontext.basedirectory, xmlfile);
c.includexmlcomments(xmlpath);
});
接着对每个api方法添加操作说明注释，以删除api来描述如下所示：
/// <summary>
/// 删除一个todoitem
/// </summary>
/// <remarks>
/// sample request:
/// delete: api/todo/2
/// </remarks>
/// <param name="id"></param>
/// <returns>不返回内容</returns>
/// <response code="204">删除成功，不返回内容</response>
/// <response code="404">删除失败，未找到该记录</response>
[httpdelete("{id}", name = "deletetodoitem")]
[producesresponsetype(204)]
[producesresponsetype(404)]
public async task<iactionresult> deletetodoitem(long id)
{
var todoitem = await _context.todoitems.findasync(id);
if (todoitem == null)
{
return notfound();
}
_context.todoitems.remove(todoitem);
await _context.savechangesasync();
return nocontent();
}
启动程序后，swagger ui 显示的delete删除api的描述如下图。还可以点击try it out按钮进行测试删除，图中显示server response 返回204删除成功。
3.2 数据注释
使用 system.componentmodel.dataannotations 命名空间中的属性来修饰模型，以帮助驱动 swagger ui 组件。下面将 [required] 属性添加到 todoitem 类的 name 属性：
[required]
public string name { get; set; }
此属性的状态更改 ui 行为并更改基础 json 架构：
将 [produces("application/json")] 属性添加到 api 控制器。 这样做的目的是声明控制器的操作支持 application/json 的响应内容类型：
[produces("application/json")]
[route("api/[controller]")]
[apicontroller]
public class todocontroller : controllerbase
{
//..
}
最后还可以自定义swagger ui，这里不在演示，可以查看官网。更多功能介绍上github。
参考文献：
如对本文有疑问，请在下面进行留言讨论，广大热心网友会与你互动！！ 点击进行留言回复
Blazor server side 自家的一些开源的, 实用型项目的进度之 CEF客户端
.NET IoC模式依赖反转(DIP)、控制反转(Ioc)、依赖注入(DI)
vue+.netcore可支持业务代码扩展的开发框架 VOL.Vue 2.0版本发布
网友评论