10-编写出色的API文档

思考并回答以下问题：

实验介绍

在本次实验中，我们将介绍如何生成API文档，包括如何使用Swagger，一种流行的API文档生成工具，来生成清晰易读且可维护的接口文档。请别忽视API文档的重要性，这是跟外部沟通交流的重要媒介，相当于系统的地图。

知识点

• Swagger
• OpenAPI

Swagger

Swagger是一种RESTful API文档生成工具，它可以自动生成API文档、代码模板等，并提供交互式API文档UI界面，以帮助开发人员更容易地了解和使用API。Swagger通过在代码注释中添加特定格式的注释，或者使用专门的Swagger编辑器来编写API文档描述文件（通常是yaml或json格式），来生成API文档。

在生成的API文档中，Swagger提供了API的所有信息，包括API的输入和输出、HTTP请求方式、请求和响应的参数、错误码等详细信息。此外，Swagger还可以生成客户端代码和服务器端代码模板，以帮助开发人员更快地构建应用程序。Swagger UI是Swagger提供的交互式API文档UI界面，它能够将生成的API文档以更友好的方式展示给开发人员，并提供了许多有用的功能，如在线测试API、查看API的请求和响应、查看API的模型等。

以下是Swagger简单示例代码，它用YAML文件来定义API。

swagger: "2.0"
info:
  title: My API
  version: 1.0.0
  description: A simple API for testing purposes
host: localhost:8080
basePath: /api
schemes:
  - http
  - https
paths:
  /users:
    get:
      summary: Get a list of all users
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string
                email:
                  type: string
                role:
                  type: string
                  enum:
                    - admin
                    - user
    post:
      summary: Create a new user
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: user
          schema:
            type: object
            properties:
              name:
                type: string
              email:
                type: string
              role:
                type: string
                enum:
                  - admin
                  - user
      responses:
        201:
          description: Created
          schema:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              email:
                type: string
              role:
                type: string
                enum:
                  - admin
                  - user

如果将这段代码复制粘贴到到Swagger Editor中，会看到如下内容。

在上个实验RESTful设计中，我们已经创建了一个简单的电商网站下单应用系统的RESTful API。现在我们需要将它们用生成Swagger API。

创建目录docs，在其中创建swagger.yaml文件，输入以下内容。

# OpenAPI 版本
openapi: "3.0.0"

# API 文档描述
info:
  title: "User Management API"
  description: "API for ecommerce"
  version: "1.0.0"

# 服务地址
servers:
  - url: "http://localhost:8080"

# 路由
paths:
  # 用户接口
  /users:
    get:
      summary: "Get a list of all users"
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/User"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
    post:
      summary: "Add a new user"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "201":
          description: "User created"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  insertedId:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
  /users/{id}:
    get:
      summary: "Get a user by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "User ID"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
    put:
      summary: "Update a user by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "User ID"
          required: true
          schema:
            type: "string"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "200":
          description: "User updated"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  message:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
    post:
      summary: "Update a user by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "User ID"
          required: true
          schema:
            type: "string"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "200":
          description: "User updated"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  message:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
    delete:
      summary: "Delete a user by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "User ID"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "User deleted"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  message:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"

  # 产品接口
  /products:
    get:
      summary: "Get a list of all products"
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/Product"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
    post:
      summary: "Add a new product"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Product"
      responses:
        "201":
          description: "Product created"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  insertedId:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
  /products/{id}:
    get:
      summary: "Get a product by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "Product ID"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "Product not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
    put:
      summary: "Update a product by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "Product ID"
          required: true
          schema:
            type: "string"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Product"
      responses:
        "200":
          description: "Product updated"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  message:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "Product not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
    post:
      summary: "Update a product by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "Product ID"
          required: true
          schema:
            type: "string"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Product"
      responses:
        "200":
          description: "Product updated"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  message:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "Product not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
    delete:
      summary: "Delete a product by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "Product ID"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Product deleted"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  message:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "Product not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
  /products/{id}/orders:
    post:
      summary: "Add a new order for a product"
      parameters:
        - name: "id"
          in: "path"
          description: "Product ID"
          required: true
          schema:
            type: "string"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
      responses:
        "201":
          description: "Order created"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  insertedId:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "Product not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"

  # 订单接口
  /orders:
    get:
      summary: "Get all orders"
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/Order"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
  /orders/{id}:
    get:
      summary: "Get an order by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "Order ID"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "Order not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
  /orders/{id}/cancel:
    post:
      summary: "Cancel an order by ID"
      parameters:
        - name: "id"
          in: "path"
          description: "Order ID"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "Order canceled"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  message:
                    type: "string"
        "400":
          description: "Bad request"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "404":
          description: "Order not found"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"
        "500":
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  error:
                    type: "string"

# 模型
components:
  schemas:
    # 用户
    User:
      type: object
      properties:
        id:
          type: string
          description: 用户 ID
        username:
          type: string
          description: 用户名
      required:
        - username
    # 产品
    Product:
      type: object
      properties:
        id:
          type: string
          description: 产品 ID
        name:
          type: string
          description: 产品名称
        price:
          type: number
          description: 产品价格
      required:
        - name
        - price
    # 订单
    Order:
      type: object
      properties:
        id:
          type: string
          description: 订单 ID
        product_id:
          type: string
          description: 产品 ID
        price:
          type: number
          description: 产品价格
        units:
          type: number
          description: 产品数量
        amount:
          type: number
          description: 订单总金额
        status:
          type: string
          description: 订单状态
      required:
        - product_id
        - price
        - units
        - amount
        - status

上面的API文档代码有些长，大概有700多行。不过，我们可以拆开来看，总共可以划分为3个重要部分：

1，元数据部分：包括openapi版本、API文档描述、服务地址等；

2，路由部分：这是API文档的重点，包括路由地址、请求方法、参数、返回等信息，具体可以参考之前的路由和控制器实验章节；

3，模型部分：RESTful接口资源的模型，例如用户、产品、订单。

同时，你可以将这部分代码复制粘贴到Swagger Editor中，可以看到类似如下结果。

OpenAPI

我们可以在Swagger YAML文件中看到openapi这个字段，其实这是一种API规范，它定义了如何描述和交互RESTful API。它使用YAML或JSON格式来描述API的接口、参数、响应和安全机制等。通过使用OpenAPI规范，可以让不同的开发者和工具能够更加轻松地理解和使用API。

相比于OpenAPI这样的接口规范，Swagger是一种用于构建、文档化和测试RESTful API的开源工具集。Swagger早期版本使用的是自己的API规范，后来它加入了OpenAPI的支持，成为OpenAPI规范的一个实现。因此，现在我们常常将OpenAPI和Swagger视为同一概念，尽管OpenAPI是规范，而Swagger是实现。

OpenAPI规范定义了如何描述API，而Swagger工具集则提供了一套工具来帮助开发者实现OpenAPI规范。例如，Swagger提供了一个UI界面来展示和测试API，也可以通过Swagger Codegen来生成API客户端和服务端的代码。因此，可以说Swagger是OpenAPI规范的一种实现方式，它帮助开发者更加方便地实现和管理API。

实验总结

本次实验基于RESTful设计章节，继续讲解如何用Swagger及OpenAPI规范来生成API文档。有了API文档，我们可以更清晰、规范的与外部系统进行沟通和交流，方便外部系统来集成我们自己开发的应用接口。同时，有了API文档，我们自己也可以从接口规范层面来约束自己的API接口输入输出，使系统更加健壮。

这是本阶段Gin框架基础的最后一个实验。相信你从本阶段的各个基础和实战实验中，对Gin框架有了进一步了解，知道了Web框架的基本架构以及必要模块，这可以为后面的进阶实验打好基础。