Swagger2 权威指南——第1章 初识Swagger
第1章 初识Swagger
本章学习目标：
- 了解什么是Swagger
- 理解OpenAPI规范
- 能够编写简单的OpenAPI定义
- 了解Swagger生态构建工具
1.1 什么是Swagger
Swagger 是一套围绕OpenAPI规范构建的开源工具，可以帮助开发人员设计、构建、记录和使用REST API。主要的Swagger工具包括：
- Swagger Editor：基于浏览器的在线编辑器，可以在其中编写OpenAPI定义。
- Swagger UI：将OpenAPI规范呈现为交互式API文档。
- Swagger Codegen：代码生成器，可以根据OpenAPI规范生成对应语言的服务端和客户端代码。
除了使用Swagger提供的工具之外，我们还可以在项目中使用Swagger提供的API文档库，配合Spring Boot可以很方便的生成对应的REST API接口文档，具体关于Spring Boot应用整合Swagger内容将在后文详细介绍。
1.2 什么是OpenAPI
既然Swagger 是基于OpenAPI规范的，那么我们有必要了解一下OpenAPI规范具体内容。
OpenAPI规范（以前成为Swagger规范）是Linux基金会的一个开源项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范可以帮助我们描述一个API的基本信息，包括：
- 有关API的一般性描述
- 每个路径上的可用操作(GET、POST等)
- 可用路径（资源）
- 每个操作的输入/输出格式
- 验证方法
- 联系信息、许可、使用条款和其他信息
1.3 为什么要使用OpenAPI
描述API自身结构是OpenAPI最根本的能力，编写完成后，OpenAPI规范和Swagger工具可以通过各种方式进一步推动您的API开发：
- 使用Swagger Codegen为你的API生成服务器存根，剩下的事情就是实现你的服务器端逻辑。
- 使用Swagger Codegen为你的API生成客户端代码库，目前已涵盖了40多种语言。
- 使用Swagger UI生成交互式API文档，使用用户可以直接在浏览器中尝试API调用。
- 使用规范将API相关工具连接到API。例如，将规范导入SoapUI以为您的API创建自动化测试。
1.4 基本结构
1.4.1 OpenAPI定义
现在我们知道想要使用Swagger我们需要根据OpenAPI规范编写符合规范的OpenAPI定义，那么我们如何来编写OpenAPI定义呢？我们可以使用YAML或者JSON语言格式来编写API定义文档，但官方更推荐以YAML方式，如下所示：
openapi: 3.0.0
info:
title: Sample API
description: #可以使用单行或多行markdown或者HTML描述
version: 0.0.1
servers:
- url: #http://api.example.com/v1
description: #可选服务器描述，例如生产服务器
- url: http://staging-api.example.com
description: #可选服务器描述，例如测试服务器
paths:
/users:
get:
summary: #接口摘要，例如：返回用户列表
descriotion: #可选扩展描述,可以用markdown或者HTML
responses:
'200': # status code
description: #描述信息
content:
application/json:
schema:
type: array
items:
type: string
注意： 所有关键字名称都区分大小写。
在上面的OpenAPI定义文件中，包含了一个API接口文档所需要的基本信息，下面我们针对各个部分详细说明。
1.4.2 元数据
每个API定义必须包含此定义所基于的OpenAPI规范的版本：
openapi: 3.0.0
OpenAPI版本定义了API定义的整体结构，info部分包含了API的基本信息：title，description（可选），version。其中title是API的名称，description是有关API的描述信息，它可以是单行或者多行文本，支持Markdown或HTML。version是API的版本号。
1.4.3 服务器
servers部分用于指定API所属服务器和基本URL，可以定义一个或者多个服务器，例如生产环境和沙箱环境：
servers:
- url: http://api.example.com/v1
description: 可选的描述信息
- url: http://staging-api.example.com
description: 可选的描述信息
这里需要注意，所有的API路径都与服务器URL相关，比如1.4.1的示例中，/users表示http://api.example.com/v1/users或http://staging-api.example.com/v1/users，具体路径取决于所在服务器的URL。
1.4.4 路径
paths部分定义了API中的各个端点（路径）以及这些端点支持的HTTP方法，例如 GET /users可以描述为：
paths:
/users:
get:
summary: #接口摘要
description: 可选描述信息
responses:
'200':
description: 描述信息
content:
application/json
schema:
type: array
items:
types: string
操作定义包括参数、请求主体（如果有）、可能的响应状态码（例如200 OK或404 Not Found）和响应内容，具体更多信息，将在后文详细介绍。
1.4.5 参数
操作可以通过URL path （/users/{userId})，query string（/usesrs?role=admin），headers（x-CustomHeader: value)或cookies（Cookie:debug=0）传递参数，并且可以定义参数的数据类型、格式、是否为必需或可选，以及其他详细信息：
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- name: userId
in: path
required: true
description: Parameter description in CommonMark or HTML.
schema:
type: integer
format: int64
minimun: 1
responses:
'200':
description: OK
有关更多参数定义，将在后文详细介绍。
1.4.6 Request Body
如果操作发送一个请求体，需要使用requestBody关键字来描述请求体内容和媒体类型：
paths:
/users:
post:
summary: Creates a user.
requestBody:
required: true
content:
application/json
schema:
type: object
properties:
username:
type: string
responses:
'201':
description: Created
1.4.7 响应
对于每个操作，可以定义可能的状态码，例如200 OK或404 Not Found，以及响应正文schema。Schemas可以被定义为内联或通过变量$ref引用，还可以为不同的内容类型提供示例响应：
paths:
/users/{userId}:
get:
summary: 根据ID查询用户信息
parameters:
- name: userId
in: path
required: true
description: 用户的ID
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: 用户对象
content:
application/json
schema:
type: object
properties:
id:
type: integer
format: int64
example: 4
name:
type: string
example: James
'400':
description: 无效的用户ID
'404':
description: 未找到指定的用户
default:
description: 未知错误
请注意，响应HTTP状态码必须用引号括起来：‘200’。
1.4.8 输入和输出模型
在OpenAPI定义文件中，全局components/schemas部分允许你定义API中使用的公共数据结构。可以使用变量$ref在各种schema中引用，比如：参数、请求体、响应体，例如下面这个JSON对象：
{
"id":4,
"name":"Arthur Dent"
}
可以表示为：
components:
schemas:
User:
properties:
id:
type: integer
name:
type: string
# 两个属性都是必需的
required:
- id
- name
然后在请求体模式和响应体模式中引用，如下所示：
paths:
/users/{userId}:
get:
summary: 根据用户ID返回一个用户对象
parameters:
- in: path
name: userId
required: true
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/users:
post:
summary: 创建一个用户
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'201':
description: Created
1.4.9 认证
在OpenAPI定义中，我们可以使用关键字securitySchemes和security来描述API中使用的身份认证方法，如下所示：
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
支持的身份验证方法有：
- HTTP身份验证：Basic、Bearer等。
- API密钥作为请求头或查询参数或在Cookie中。
- OAuth
- OpenID Connect Discovery
具体身份验证方法定义，将在后文详细介绍。
1.5 小结
本章主要从Swagger的作用及相关概念出发，重点介绍了如何使用OpenAPI规范定义API接口，学习本章可以简单了解OpenAPI规范，掌握简单的API接口定义方法，后续章节将从各个知识点逐步深入介绍完整的Swagger技术要点。