Swagger3详细解析

一、什么是Swagger3

Swagger是一个Api文档工具，可根据代码创建、设计和文档化API。Swagger3是这个工具的最新版本，是一个开源的API文档规范，可帮助开发人员设计、构建、文档、测试和消费RESTful Web服务。

用Swagger3的好处包括：

1、提供可读性强的API文档

2、简化HTTP API测试过程

3、提供客户端SDK、代码生成器、模拟器和自动化构建和发布工具

二、如何使用Swagger3

1、安装Swagger3

要使用Swagger3，需要从GitHub网站下载Swagger的源代码，并将其构建到本地计算机上。在下载并构建完Swagger3之后，即可在项目中使用Swagger3。

2、添加Swagger3注释

Swagger3使用特殊的API注释语法，可将API元数据和其他信息直接嵌入到代码中。这个注释语法称为Swagger注释。

Swagger3注释最少需要包含以下四类注释：

1、@swagger

2、@Operation

3、@ApiParam

4、@ApiResponse

/**
 * @swagger
 * /api/user:
 *   post:
 *     summary: 创建用户
 *     tags:
 *       - User
 *     requestBody:
 *       description: 用户相关信息
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               username:
 *                 type: string
 *                 example: john_doe
 *               email:
 *                 type: string
 *                 example: john_doe@example.com
 *     responses:
 *       200:
 *         description: 用户创建成功
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       400:
 *         description: 参数错误
 *       500:
 *         description: 服务器错误
 */

3、生成Swagger3文档

有两种主要方法可以生成Swagger3文档：

1、使用Swagger UI：Swagger UI是一个用于呈现Swagger文档的用户界面。Swagger UI可以自动从API定义中提取Swagger3元数据，并使用这些元数据创建可视化API文档。

2、使用Swagger Codegen：Swagger Codegen是Swagger项目的一个工具，可根据Swagger3文档生成API客户端库、服务器存根、文档和测试代码。

三、Swagger3的扩展

1、OpenAPI3

OpenAPI3是Swagger3的升级版。它是一个基于JSON和YAML的标准，用于描述RESTful Web服务API。OpenAPI3增加了许多有用的功能，包括：

1、提供支持RESTful Web服务的异步API

2、提供扩展机制，可以添加自定义功能

3、提供更好的安全性功能，例如JWT和OAuth 2.0

4、支持更多的API风格，包括GraphQL和gRPC。

2、SwaggerHub

SwaggerHub是Swagger的云服务版本。它可以让团队协作在Swagger API的设计、测试和文档化方面更加轻松。SwaggerHub提供Git集成、版本控制、访问控制、自动生成的API文档和导入/导出功能等特性。

3、SwaggerCodegen

SwaggerCodegen是Swagger的代码生成工具。它可以支持许多不同的编程语言和框架，包括Java、Python、Ruby、C#、JavaScript和TypeScript等。SwaggerCodegen使开发人员能够省去编写模板代码的烦恼，以便他们可以更快地构建Web API。

四、Swagger3示例代码

const express = require('express');
const app = express();
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const swaggerOptions = {
  swaggerDefinition: {
    info: {
      version: "1.0.0",
      title: "Customer API",
      description: "Customer API Information",
      contact: {
        name: "Amazing Developer"
      },
      servers: ["http://localhost:3000"]
    }
  },
  apis: ["app.js"]
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocs));

/**
 * @swagger
 * /customers:
 *   get:
 *     description: Get all customers
 *     responses:
 *       200:
 *         description: Success
 * 
 *   post:
 *     description: Create a new customer
 *     parameters:
 *       - name: name
 *         description: Customer's name
 *         in: formData
 *         required: true
 *         type: string
 *       - name: email
 *         description: Customer's email
 *         in: formData
 *         required: true
 *         type: string
 *       - name: phone
 *         description: Customer's phone
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: Success
 * 
 * @swagger
 * /customers/{id}:
 *   get:
 *     description: Get a customer by ID
 *     parameters:
 *       - name: id
 *         description: Customer's ID
 *         in: path
 *         required: true
 *         type: integer
 *     responses:
 *       200:
 *         description: Success
 * 
 *   put:
 *     description: Update a customer by ID
 *     parameters:
 *       - name: id
 *         description: Customer's ID
 *         in: path
 *         required: true
 *         type: integer
 *       - name: name
 *         description: Customer's name
 *         in: formData
 *         required: true
 *         type: string
 *       - name: email
 *         description: Customer's email
 *         in: formData
 *         required: true
 *         type: string
 *       - name: phone
 *         description: Customer's phone
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: Success
 * 
 *   delete:
 *     description: Delete a customer by ID
 *     parameters:
 *       - name: id
 *         description: Customer's ID
 *         in: path
 *         required: true
 *         type: integer
 *     responses:
 *       200:
 *         description: Success
 */
app.get('/customers', (req, res) => {
  res.send('Get all customers');
});

app.post('/customers', (req, res) => {
  res.send('Create a customer');
});

app.get('/customers/:id', (req, res) => {
  res.send(`Get a customer by ID: ${req.params.id}`);
});

app.put('/customers/:id', (req, res) => {
  res.send(`Update a customer by ID: ${req.params.id}`);
});

app.delete('/customers/:id', (req, res) => {
  res.send(`Delete a customer by ID: ${req.params.id}`);
});

app.listen(3000, function() {
  console.log('Server started');
});