?

目錄

1、直接使用swagger-ui-express

2、配合swagger-jsdoc

---

?

如何在Node.js項目中使用 Swagger 來自動生成 API接口文檔，使用生成方式有很多種。本文基于swagger-jsdoc+swagger-ui-express快速實現(xiàn)

1、直接使用swagger-ui-express

// 方便來瀏覽和測試api
npm i swagger-ui-express

?

import { Express } from 'express';
import swaggerUi from 'swagger-ui-express';
const options = {openapi: "3.0.3",info: {title: '文檔相關接口',version: '1.0.0',description: 'API documentation using Swagger',},tags: [{name: "develop",description: "開發(fā)者站點管理接口",}],paths: {"/develop": {"get": {"tags": ["develop"],"description": "獲取文檔列表!","responses": {"200": {"description":"返回字符串數(shù)組"}}}}}
}
const swaggerInstall = (app: Express) => {app.use('/apidoc',swaggerUi.serve,swaggerUi.setup(options));
};
export { swaggerInstall };

直接使用配置去生成接口文檔，更改接口的時候需要同時去更改配置，會相對麻煩點。這時候就可以使用swagger-jsdoc,通過在接口上面注釋信息后，就可以自動更新對應的api接口文檔，其本質(zhì)是通過讀取該接口對應的注釋，然后再轉(zhuǎn)成對應的配置。

2、配合swagger-jsdoc

• JSDoc 注釋是一種特殊的注釋語法，用于為 JavaScript 代碼添加文檔化和類型提示信息。它是基于 JSDoc 規(guī)范的一部分，旨在提供一種標準的方式來描述代碼的結(jié)構(gòu)、功能和類型信息

• 作用：接口文檔注釋有更新，對應的api文檔會同步更新。確保接口變更，配置會同時去更改

npm i swagger-jsdoc

?

import { Express } from 'express';
import path from 'path';
import swaggerDoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';const swaggerOptions = {swaggerDefinition: {info: {title: '文檔相關接口',version: '1.0.0',description: 'API documentation using Swagger',},},apis: [path.join(__dirname, './routes/*.ts')], // 指定包含 API 路由的文件或文件夾路徑
};
const swaggerInstall = (app: Express) => {app.use('/apidoc',swaggerUi.serve,swaggerUi.setup(swaggerDoc(swaggerOptions)));
};
export { swaggerInstall };

?

//在對應的接口，注釋對應的文檔
import express from 'express';
import {developGetFile,developGetFileList,
} from '../controllers/developControllers';
const router = express.Router();
/*** @openapi* /develop:*   get:*     tags: [develop]*     description: 獲取文檔列表!*     responses:*       200:*         description: 返回字符串數(shù)組.*/
router.get('/', developGetFileList);

?