(29)ASP.NET Core3.1 Swagger(OpenAPI)

时间:2024-01-26 18:15:15

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