一文探討Node.js專案中怎麼使用Koa2整合Swagger

在本文中，我們將探討如何在Node.js專案中使用Koa2整合Swagger，以自動產生API文件。我們將介紹Swagger的基本概念、相關的NPM包，並透過詳細的程式碼範例和解釋來演示整個過程。

什麼是Swagger

Swagger是一款RESTful API的文件產生工具，它可以幫助開發者快速、精確地編寫、維護和查閱API文件. Swagger具有以下優點：

• 自動產生API文檔，減少手動編寫的工作量
• #提供可視化的API介面測試工具，方便調試和驗證
• 支持多種語言和框架，具有良好的通用性和可擴展性

創建Koa2專案

首先，我們需要建立一個基於Koa2的Node.js專案。你可以使用以下指令建立專案：【相關教學推薦：nodejs影片教學、程式設計教學】

mkdir koa2-swagger-demo
cd koa2-swagger-demo
npm init -y

然後，安裝Koa2和相關依賴：

npm install koa koa-router --save

安裝Swagger相關依賴

接下來，我們需要安裝Swagger相關的NPM套件。在本教程中，我們將使用koa2-swagger-ui和swagger-jsdoc。分別用於展示Swagger UI和產生API文件。

npm install koa2-swagger-ui swagger-jsdoc --save

配置Swagger

在專案根目錄下，建立一個名為swagger.js的文件，用於設定Swagger。設定程式碼如下：

const swaggerJSDoc = require('swagger-jsdoc');
const options = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: '我是标题',
            version: '1.0.0',
            description: '我是描述',
        },
        //servers的每一项，可以理解为一个服务,实际项目中，可自由修改
        servers: [
            {
                url: '/api',
                description: 'API server',
            },
        ],
    },
    apis: ['./routes/*.js'],
};

const swaggerSpec = swaggerJSDoc(options);

// 如果有Swagger规范文件转TS的需求，可在此处保留Swagger规范文件到本地，方便使用
//fs.writeFileSync('swagger.json', JSON.stringify(swaggerSpec, null, 2));

module.exports = swaggerSpec;

這裡，我們定義了一個名為options的對象，包含了Swagger的基本資訊和API介面的來源（即我們的路由檔案）。然後，我們使用swagger-jsdoc產生API文檔，並將其匯出。

寫API介面

現在，我們來建立一個名為routes的資料夾，並在其中建立一個名為users.js#的文件，用於定義使用者相關的API介面。在users.js檔案中，我們將編寫以下程式碼：

const Router = require('koa-router');
const router = new Router();

/**
* @swagger
* tags:
*   name: Users
*   description: User management
*/

/**
* @swagger
* components:
*   schemas:
*     User:
*       type: object
*       properties:
*         id:
*           type: integer
*           description: The user ID.
*         name:
*           type: string
*           description: The user's name.
*         email:
*           type: string
*           description: The user's email.
*       required:
*         - id
*         - name
*         - email
*/

/**
* @swagger
* /users:
*   get:
*     summary: Retrieve a list of users
*     tags: [Users]
*     responses:
*       200:
*         description: A list of users.
*         content:
*           application/json:
*             schema:
*               type: array
*               items:
*                 $ref: '#/components/schemas/User'
*/
router.get('/users', async (ctx) => {
    const users = [
        { id: 1, name: 'John Doe', email: 'john.doe@example.com' },
        { id: 2, name: 'Jane Doe', email: 'jane.doe@example.com' },
    ];
    ctx.body = users;
});

module.exports = router;

註解簡析：

1. tags： 這部分定義了一個名為"Users"的標籤。標籤用於對API介面進行分類和分組。在這裡，標籤名為"Users"，描述為"users.js下的介面"。

   /**
    * @swagger
    * tags:
    *   name: Users
    *   description: users.js下的接口
    */

2. components和schemas： 這部分定義了一個名為"User"的資料模型。資料模型描述了API介面中使用的資料結構。在這個範例中，"User"模型包含三個屬性：id（整數類型，表示使用者ID）、name（字串類型，表示使用者名稱）和 email（字串類型，表示使用者電子郵件）。同時，id、name和email屬性都被標記為必要。

   /**
    * @swagger
    * components:
    *   schemas:
    *     User:
    *       type: object
    *       properties:
    *         id:
    *           type: integer
    *           description: id.
    *         name:
    *           type: string
    *           description: name.
    *         email:
    *           type: string
    *           description: email.
    *       required:
    *         - id
    *         - name
    *         - email
    */

3. /users API介面： 這部分定義了一個取得使用者清單的API介面。它描述了一個GET請求，路徑為/users。這個介面使用了先前定義的"Users"標籤。另外，它也定義了一個成功的回應，狀態碼為200，表示傳回一個使用者清單。回應的內容類型為application/json，其結構為包含"User"模型的陣列。

   $ref: '#/components/schemas/User' 是引用語法，引用了先前定義在components下的schemas#中名為User的資料模型。

   /**
   * @swagger
   * /users:
   *   get:
   *     summary: 获取用户列表
   *     tags: [Users]
   *     responses:
   *       200:
   *         description: success.
   *         content:
   *           application/json:
   *             schema:
   *               type: array
   *               items:
   *                 $ref: '#/components/schemas/User'
   */

這段程式碼為API文件提供了有關使用者管理介面、資料模型和回應格式的詳細資訊。 Swagger JSDoc解析這些註釋，並產生對應的OpenAPI文件。

產生API文件

接下來，我們需要在專案中啟用Swagger UI。在專案根目錄下，建立一個名為app.js的文件，然後編寫以下程式碼：

const Koa = require('koa');
const Router = require('koa-router');
const swaggerUI = require('koa2-swagger-ui').koaSwagger;
const swaggerSpec = require('./swagger');
const usersRoutes = require('./routes/users');

const app = new Koa();
const router = new Router();

router.use('/api', usersRoutes.routes(), usersRoutes.allowedMethods());

router.get(
    '/swagger',
    swaggerUI({
        routePrefix: false,
        swaggerOptions: {
            spec: swaggerSpec,
        },
    })
);

app.use(router.routes()).use(router.allowedMethods());

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server is running at http://localhost:${PORT}`);
});

在這裡，我們導入了koa2-swagger-ui和swagger-jsdoc產生的API文件。然後，我們定義了一個名為/swagger的路由，用來展示Swagger UI。最後，我們將使用者相關的API介面掛載到/api路徑下。

測試

node app.js

在瀏覽器中開啟http://localhost:3000/swagger 你將會看到Swagger UI及自動產生的API文件。

總結

在本文中，我們詳細介紹如何在基於Koa2的Node.js專案中整合Swagger並自動產生API文件。透過使用koa2-swagger-ui和swagger-jsdoc，我們可以輕鬆地為API介面產生線上文檔，並利用Swagger UI進行視覺化測試。

整合Swagger的主要步驟如下：

• 安裝相關依賴：koa2-swagger-ui和swagger-jsdoc
• 配置Swagger：建立swagger.js文件，定義API文件的基本資訊與介面來源
• 撰寫API介面：使用Swagger註解語法描述介面資訊
• 啟用Swagger UI：在app.js中設定Swagger UI的路由，並將API文件傳遞給它
• 運行專案並存取Swagger UI

透過以上步驟，我們可以在專案中實作API文件的自動產生、更新和查閱，從而提高開發效率和協作效果。同時，利用Swagger UI提供的測試工具，我們也可以輕鬆驗證API介面的正確性和穩定性。

可以使用swagger-to-ts將Swagger規格檔案轉換為TypeScript類型檔案。

更多node相關知識，請造訪：nodejs 教學！

以上是一文探討Node.js專案中怎麼使用Koa2整合Swagger的詳細內容。更多資訊請關注PHP中文網其他相關文章！