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技术要点。