ASP.NET Core 使用Swagger/OpenAPI文档化API

为了了解什么是Swagger以及OpenAPI，在本节开始之前，我们通过一个故事介绍一下Swagger的来源：Swagger项目的来源可以追溯到2011年，由大名鼎鼎Wordnik字典站点(https://www.wordnik.com/)的技术联合创始人Tony Tam创建，在Wordnik产品的开发过程中，他们遇到了自动化API文档和客户端SDK生成的需求，这成为一个主要的挑战，为了解决这个问题，Tony Tam设计了一种简单的JSON表示方式，利用了HTTP协议的灵活性，并借鉴了为SOAP协议构建的一些工具的特性

在这个过程中，团队逐渐形成了Swagger项目，并于2011年9月将其开源，这个项目的初衷是为了提供一种简便的方式来描述、文档化和消费RESTful API，在Swagger的早期阶段，它获得了一些小公司和独立开发者的关注，因为HTTP API通常没有一个可机器读取的描述机制，而Swagger提供了一个相对简单和易于理解的方法

由于Swagger的成功，它在API行业中逐渐引起了更广泛的关注。在2015年11月，SmartBear Software公司（当时Swagger的维护者）宣布帮助创建一个新的组织，即OpenAPI Initiative，由Linux基金会赞助。这标志着Swagger的演进，而Swagger规范最终更名为OpenAPI规范

整个Swagger项目的发展源于对API文档和开发工具的实际需求，旨在简化API的设计、文档化和消费过程

简而言之：

• OpenAPI 是Swagger项目发展中形成的一种规范
  

• Swagger项目在整个过程中也符合OpenAPI规范的工具集，例如 OpenAPIGenerator 和 SwaggerUI

在.NET 中主要有两个实现OpenAPI标准的库，分别为：

• Swashbuckle 库

  github:https://github.com/domaindrivendev/Swashbuckle.AspNetCore

• NSwag 库

  github:https://github.com/RicoSuter/NSwag

1. Open API规范

Open API规范是用来描述API的文档，该文档基于控制器中的xml注释以及实体类属性attribute特性，它是 OpenAPI 流程的核心，从而用来驱动 SwaggerUI 等工具进行展示，默认情况下，它的名称为 openapi.json。以下是一个简化的 OpenAPI 规范示例：

2. Swagger UI

Swagger UI使用生成的OpenAPI规范通过Web UI的方式来描述服务信息，在AspNet Core 注册相关的中间件时Swashbuckle和NSwag都包含了Swagger UI，我们在项目中启用如下选项，右击项目->Build->Output，默认该项是非选中状态，我们将它选中，用来更友好描述我们的API

在启动类中添加如下代码：

运行结果如下：

源代码地址：

https://github.com/bingbing-gui/Asp.Net-Core-Skill/tree/master/Fundamentals/AspNetCore.Swagger/AspNetCore.Swashbuckle