（29）ASP.NET Core3.1 Swagger（OpenAPI）

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入门