1.什么是swagger/openapi？
swagger是一个与语言无关的规范，用于描述rest api。因为swagger项目已捐赠给openapi计划，所以也叫openapi。它允许计算机和人员了解服务的功能，可以直接在线访问测试api方法。而swagger ui提供了基于web的ui，它使用生成的swagger规范提供有关服务api的信息。swashbuckle和nswag均包含swagger ui的嵌入式版本，因此可使用中间件注册调用将该嵌入式版本托管在asp.net core应用程序当中。swagger的核心是swagger规范，默认情况下是名为swagger.json的文档。它由swagger工具链（或其第三方实现）根据你的服务生成。它描述了api的功能以及使用http对其进行访问的方式。它驱动swagger ui，并由工具链用来启用发现和客户端代码生成。
2.net swagger实现
net swagger实现分为两大分类：
●swashbuckle.aspnetcore是一个开源项目，用于生成asp.net core web api的swagger文档。
●nswag是另一个用于生成swagger文档并将swagger ui或redoc集成到asp.net core web api中的开源项目。此外，nswag 还提供了为api生成c#和typescript客户端代码的方法。
但是由于工作比较忙，我就不打算两个类型都讲了，我只选择swashbuckle.aspnetcore来讲解和演示。
3.swashbuckle主要组成部分
swashbuckle有三个主要组成部分：
swashbuckle.aspnetcore.swagger：将swaggerdocument对象公开为json终结点的swagger对象模型和中间件。
swashbuckle.aspnetcore.swaggergen：从路由、控制器和模型直接生成swaggerdocument对象的swagger生成器。它通常与swagger终结点中间件结合，以自动公开swagger json。
swashbuckle.aspnetcore.swaggerui：swagger ui工具的嵌入式版本。它解释swagger json以构建描述web api功能的可自定义的丰富体验，它包括针对公共方法的内置测试工具。
安装swashbuckle组件方法有两种：
--powershell install-package swashbuckle.aspnetcore -version 5.0.0
or
--.net core cli dotnet add todoapi.csproj package swashbuckle.aspnetcore -v 5.0.0
4.什么是rest?
我百度一下，度娘解释是：rest是（representational state transfer）“表现层状态转移”的缩写，它是由罗伊·菲尔丁（roy fielding）提出的，是用来描述创建http api的标准方法，他发现这四种常用的行为“查看（view），创建（create），编辑（edit）和删除（delete）”都可以直接映射到http中已实现的get、post、put和delete方法。
5.配置swagger中间件
将swagger生成器添加到startup.configureservices方法中的服务集合中：
//注册swagger生成器，定义一个或多个swagger文档.
services.addswaggergen(c =>
{
c.swaggerdoc("v1", new openapiinfo { title = "my api", version = "v1", description = "测试描述" });
});
openapiinfo对象是用来标识swagger文档信息（诸如作者、许可证和说明的信息），您还可以自定义您的主题的信息显示在ui上，详情配置，我就不多说，大家可以看官网描述，如上述openapilnfo信息配置示例图：
而在启动应用程序后并导航到http://localhost:<port>/swagger/v1/swagger.json。生成的描述终结点的文档显示在swagger规范（swagger.json）中：
在startup.configure方法中，启用中间件为生成的json文档和swagger ui提供服务：
//使中间件能够将生成的swagger用作json端点.
app.useswagger();
//允许中间件为swagger ui（html、js、css等）提供服务，指定swagger json端点.
app.useswaggerui(c =>
{
c.swaggerendpoint("/swagger/v1/swagger.json", "my api v1");
});
根据上述配置就能够启用swagger测试api服务接口了，如下图所示：
6.xml注释
swagger还可以把服务api中对应方法名称，实体属性注释给在ui上显示出来，让您更加直观了解每个方法使用信息，并对没有注释每个方法进行警告提示，具体启用xml注释操作在“解决方案资源管理器”中右键单击该项目，然后选择“编辑<project_name>.csproj”，手动将突出显示的行添加到.csproj 文件：
<propertygroup> <generatedocumentationfile>true</generatedocumentationfile> </propertygroup>
在启用了xml注释后，swagger只会针对没有添加注释每个方法进行警告提示，而添加了注释的方法则不会进行警告提示：
而每个添加了注释的方法会通过在startup.configureservices/services.addswaggergen中设置swagger json和ui的注释路径后：
//设置swagger json和ui的注释路径.
var xmlfile = $"{assembly.getexecutingassembly().getname().name}.xml";
var xmlpath = path.combine(appcontext.basedirectory, xmlfile);
c.includexmlcomments(xmlpath);
会在项目根目录生成的一个对应项目文件名的xml文件，而文件里面就包含所有已注释的方法，用于ui上显示：
在启动应用程序后，我们会看到每个有注释方法在左侧会有一行文字描述，效果如下图所示：
如果某个方法或者类下面所有方法不想警告提示，可以通过加入#pragma warning disable声明屏蔽警告提示：
加入声明之后，大家会看到警告提示消失了。
7.数据注释
可以使用system.componentmodel.dataannotations命名空间中的属性来标记模型实体，以帮助驱动swagger ui 组件。将[required]属性添加到todoitem类的name属性：
namespace todoapi.models
{
public class todoitem
{
public long id { get; set; }
[required]
public string name { get; set; }
[defaultvalue(false)]
public bool iscomplete { get; set; }
}
}
此属性的状态会更改掉基础json架构：
而将[produces(“application/json”)]属性添加到api控制器去，这样做的目的是声明控制器的操作支持application/json的响应内容类型：
[produces("application/json")]
[route("api/[controller]")]
[apicontroller]
public class valuescontroller : controllerbase
{
/// <summary>
/// 获取值
/// </summary>
/// <returns></returns>
// get api/values
[httpget]
public async task<actionresult<ienumerable<string>>> get()
{
var result = await new githubapi().getuser();
return new string[] { result.id.value.tostring(), result.login };
}
}
“响应内容类型”下拉列表选此内容类型作为控制器的默认get操作：
swagger/openapi出现，大大减少开发者调试时间，增加开发者开发效率，让开发者更加方便调试跟直观了解对应服务方法。
参考文献：
swashbuckle和asp.net core入门
