快捷導(dǎo)航

Node.js自動(dòng)生成API文檔的實(shí)現(xiàn)

更新時(shí)間：2024年03月05日 09:47:12 作者：王果凍ddd

本文主要介紹了Node.js自動(dòng)生成API文檔,包含基于swagger-jsdoc+swagger-ui-express快速實(shí)現(xiàn),具有一定的參考價(jià)值,感興趣的可以了解一下

1、直接使用swagger-ui-express

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

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

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

2、配合swagger-jsdoc

JSDoc 注釋是一種特殊的注釋語法，用于為 JavaScript 代碼添加文檔化和類型提示信息。它是基于 JSDoc 規(guī)范的一部分，旨在提供一種標(biāo)準(zhǔn)的方式來描述代碼的結(jié)構(gòu)、功能和類型信息
作用：接口文檔注釋有更新，對(duì)應(yīng)的api文檔會(huì)同步更新。確保接口變更，配置會(huì)同時(shí)去更改

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: '文檔相關(guān)接口',
      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 };

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

到此這篇關(guān)于Node.js自動(dòng)生成API文檔的文章就介紹到這了,更多相關(guān)Node.js自動(dòng)生成API內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: