在nodejs中使用swagger方式

更新時(shí)間：2022年09月06日 15:02:13 作者：青淺l

這篇文章主要介紹了在nodejs中使用swagger方式，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教

在nodejs中使用swagger

在工作中和后臺(tái)javaer進(jìn)行接口調(diào)試的時(shí)候使用的是swagger,非常的方便。nodejs中有什么好用的api工具呢？網(wǎng)上查找了一下，swagger同樣適用于nodejs,記錄一下在nodejs中使用swagger的過(guò)程。

1、安裝依賴

npm install swagger-ui-express swagger-jsdoc -S

2、創(chuàng)建swagger中間件

在utils/swagger文件夾中創(chuàng)建index.js
配置swagger-jsdoc中的options
注意修改swagger收集注釋的路由

const path = require('path')
const express = require('express')
const swaggerUI = require('swagger-ui-express')
const swaggerDoc = require('swagger-jsdoc')
//配置swagger-jsdoc
  const options = {
    definition: {
      openapi: '3.0.0',
      info: {
        title: 'api',
        version: '1.0.0',
        description: `小程序+管理后臺(tái)共用接口api`
      }
    },
    // 去哪個(gè)路由下收集 swagger 注釋
    apis: [path.join(__dirname,'../../routes/*.js')]
  }
  var swaggerJson = function (req, res) {
    res.setHeader('Content-Type', 'application/json');
    res.send(swaggerSpec);
  }
  const swaggerSpec = swaggerDoc(options)
  
  var swaggerInstall = function(app) {
    if (!app){
      app = express()
    }
    // 開(kāi)放相關(guān)接口，
    app.get('/swagger.json', swaggerJson);
    // 使用 swaggerSpec 生成 swagger 文檔頁(yè)面，并開(kāi)放在指定路由
    app.use('/swagger', swaggerUI.serve, swaggerUI.setup(swaggerSpec));
  }
  module.exports = swaggerInstall

3、在app.js中引用swagger中間件的swaggerInstall方法

// 使用swagger API 文檔
var swaggerInstall = require('./utils/swagger')
swaggerInstall(app)

4、swagger 在js 中的注釋如下所示

可在配置的路徑下任意js地方注釋，swagger-jsdoc會(huì)遍歷查找

/**,
 * @swagger
 * /api/addExam:
 *    post:
 *      tags:
 *      - 測(cè)試
 *      summary: 提交考試答案
 *      produces:
 *      - application/json
 *      parameters:
 *      - name: name
 *        in: query
 *        description: 姓名
 *        required: false
 *        type: integer
 *        maximum:
 *        minimum: 1
 *        format:
 *      - name: phone
 *        in: query
 *        description: 電話
 *        required: false
 *        type: integer
 *        maximum:
 *        minimum: 1
 *        format:
 *      responses:
 *        200:
 *          description: successful operation
 *          schema:
 *            ref: #/definitions/Order
 *        400:
 *          description: Invalid ID supplied
 *        404:
 *          description: Order not found
 * */

5、訪問(wèn)api

npm start 運(yùn)行項(xiàng)目
輸入 http://localhost:3000/swagger 訪問(wèn)本地api

swagger api

nodejs egg框架自動(dòng)生成swagger文檔

npm install egg-swagger-doc --save

/* /config/config.default.js */
/ egg-swagger-doc 配置信息。
exports.swaggerdoc = {
    dirScanner: './app/controller', // 配置自動(dòng)掃描的控制器路徑。
    // 接口文檔的標(biāo)題，描述或其它。
    apiInfo: {
        title: 'NAPI',  // 接口文檔的標(biāo)題。
        description: 'swagger-ui for NAPI document.',   // 接口文檔描述。
        version: '1.0.0',   // 接口文檔版本。
    },
    schemes: ['http', 'https'], // 配置支持的協(xié)議。
    consumes: ['application/json'], // 指定處理請(qǐng)求的提交內(nèi)容類型（Content-Type），例如application/json, text/html。
    produces: ['application/json'], // 指定返回的內(nèi)容類型，僅當(dāng)request請(qǐng)求頭中的(Accept)類型中包含該指定類型才返回。
    securityDefinitions: {  // 配置接口安全授權(quán)方式。
        // apikey: {
        //   type: 'apiKey',
        //   name: 'clientkey',
        //   in: 'header',
        // },
        // oauth2: {
        //   type: 'oauth2',
        //   tokenUrl: 'http://petstore.swagger.io/oauth/dialog',
        //   flow: 'password',
        //   scopes: {
        //     'write:access_token': 'write access_token',
        //     'read:access_token': 'read access_token',
        //   },
        // },
    },
    enableSecurity: false,  // 是否啟用授權(quán)，默認(rèn) false（不啟用）。
    // enableValidate: true,    // 是否啟用參數(shù)校驗(yàn)，默認(rèn) true（啟用）。
    routerMap: true,    // 是否啟用自動(dòng)生成路由，默認(rèn) true (啟用)。
    enable: true,   // 默認(rèn) true (啟用)。
};

* /config/plugin.js */
'use strict';
 
// 配置 egg-swagger-doc 插件信息。
exports.swaggerdoc = {
    enable: true,   // 是否啟用。
    package: 'egg-swagger-doc', // 指定包名稱。
};

/* /app/contract/format.js */
//自動(dòng)文檔約定
module.exports = {
    JsonBody: { // 這個(gè)名字對(duì)應(yīng)上面 Controller 注釋的@response 的 JsonBody。
        result: { type: 'string' }, // 服務(wù)器返回的數(shù)據(jù)。
    },
};

編寫一個(gè)controller控制器

'use strict';
 
const BaseController = require("../base");
/**
* @controller 測(cè)試控制器 注釋必寫，swagger-doc是根據(jù)這段注釋來(lái)生成接口的 ）。
*/
class HomeController extends BaseController {
   /**  （ 注釋必寫，swagger-doc是根據(jù)這段注釋來(lái)生成接口詳細(xì)信息的 ）。
    * @summary 根據(jù)ID查詢信息。
    * @description 根據(jù)ID查詢信息。
    * @router get /api （ get 表示設(shè)置請(qǐng)求為 get 請(qǐng)求，最后的 selectById 對(duì)應(yīng)下面的 selectById 方法 ）。
    * @request query integer Id 需要去查新的ID。（ get 對(duì)應(yīng) query 請(qǐng)求，請(qǐng)求值設(shè)定為 integer 純數(shù)字類型，ID 為請(qǐng)求的字段，注意大小寫，和下面的方法要一一對(duì)應(yīng)，不然會(huì)報(bào)錯(cuò) ）。
    * @response 200 JsonBody 返回結(jié)果。（ 對(duì)應(yīng) contract 里面的驗(yàn)證屬性，下面會(huì)提到 。）
    */
  async index() {
    const { ctx } = this;
   
    let result = await this.app.mysql.query(
      'select * from user'
      );
      this.notFound()
  }
 
  async v1(){
    const { ctx } = this;
    ctx.body = "我是v1自動(dòng)路由";
  }
}
 
module.exports = HomeController;

以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。

您可能感興趣的文章: