目錄
什麼是Swagger
創建Koa2專案
安裝Swagger相關依賴
配置Swagger
寫API介面
註解簡析:
產生API文件
測試
總結
首頁 web前端 js教程 一文探討Node.js專案中怎麼使用Koa2整合Swagger

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

Apr 01, 2023 am 07:30 AM
前端 node.js 測試

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

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

什麼是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-uiswagger-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. componentsschemas: 這部分定義了一個名為"User"的資料模型。資料模型描述了API介面中使用的資料結構。在這個範例中,"User"模型包含三個屬性:id(整數類型,表示使用者ID)、name(字串類型,表示使用者名稱)和 email(字串類型,表示使用者電子郵件)。同時,idnameemail屬性都被標記為必要。

    /**
     * @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中文網其他相關文章!

本網站聲明
本文內容由網友自願投稿,版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容,請聯絡admin@php.cn

熱AI工具

Undresser.AI Undress

Undresser.AI Undress

人工智慧驅動的應用程序,用於創建逼真的裸體照片

AI Clothes Remover

AI Clothes Remover

用於從照片中去除衣服的線上人工智慧工具。

Undress AI Tool

Undress AI Tool

免費脫衣圖片

Clothoff.io

Clothoff.io

AI脫衣器

AI Hentai Generator

AI Hentai Generator

免費產生 AI 無盡。

熱門文章

R.E.P.O.能量晶體解釋及其做什麼(黃色晶體)
2 週前 By 尊渡假赌尊渡假赌尊渡假赌
倉庫:如何復興隊友
4 週前 By 尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island冒險:如何獲得巨型種子
3 週前 By 尊渡假赌尊渡假赌尊渡假赌

熱工具

記事本++7.3.1

記事本++7.3.1

好用且免費的程式碼編輯器

SublimeText3漢化版

SublimeText3漢化版

中文版,非常好用

禪工作室 13.0.1

禪工作室 13.0.1

強大的PHP整合開發環境

Dreamweaver CS6

Dreamweaver CS6

視覺化網頁開發工具

SublimeText3 Mac版

SublimeText3 Mac版

神級程式碼編輯軟體(SublimeText3)

furmark怎麼看?-furmark怎麼算合格? furmark怎麼看?-furmark怎麼算合格? Mar 19, 2024 am 09:25 AM

furmark怎麼看?-furmark怎麼算合格?

PHP與Vue:完美搭檔的前端開發利器 PHP與Vue:完美搭檔的前端開發利器 Mar 16, 2024 pm 12:09 PM

PHP與Vue:完美搭檔的前端開發利器

加入全新仙俠冒險! 《誅仙2》「無為測試」預下載開啟 加入全新仙俠冒險! 《誅仙2》「無為測試」預下載開啟 Apr 22, 2024 pm 12:50 PM

加入全新仙俠冒險! 《誅仙2》「無為測試」預下載開啟

前端面試官常問的問題 前端面試官常問的問題 Mar 19, 2024 pm 02:24 PM

前端面試官常問的問題

不同語言的函數測試與覆蓋率有什麼不同? 不同語言的函數測試與覆蓋率有什麼不同? Apr 27, 2024 am 11:30 AM

不同語言的函數測試與覆蓋率有什麼不同?

國產FPS新王炸! 《三角洲行動》大戰場超乎預期 國產FPS新王炸! 《三角洲行動》大戰場超乎預期 Mar 07, 2024 am 09:37 AM

國產FPS新王炸! 《三角洲行動》大戰場超乎預期

Django是前端還是後端?一探究竟! Django是前端還是後端?一探究竟! Jan 19, 2024 am 08:37 AM

Django是前端還是後端?一探究竟!

什麼是前端模組化ESM? 什麼是前端模組化ESM? Feb 25, 2024 am 11:48 AM

什麼是前端模組化ESM?

See all articles