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');
});