ApiDoc-接口文檔生成工具

說明

示例采用express項目

安裝

npm i apidoc -g

需要先安裝node.js

配置apidoc.json

在項目的根目錄下新建一個apidoc.json,進行如下配置

{
  "name": "ScheduleAPIs",
  "version": "1.0.0",
  "description": "日程接口文檔",
  "title": "ScheduleAPIs",
  "url" : "http://localhost:3000/"
}

name：接口文檔名稱
version: 接口文檔版本
description： 接口文檔描述
title: 文檔打開時瀏覽器顯示標題
url: 接口缺省訪問地址

接口寫在router文件夾下

使用樣例如下：

/**
 * @api {get} /mission/add 添加任務
 * @apiVersion 1.0.0
 * @apiName addMission
 * @apiGroup Mission
 * @apiParam {String} date 添加時間
 * @apiParam {String} mission 任務內容
 * @apiParam {String} flag 是否完成，默認0未完成
 * @apiSuccess {Number} code 結果標識
 * @apiSuccess {String} message 結果說明
 * @apiSuccess {Object} data 結果數據
 * @apiSuccessExample Success-Response:
 *     {
        code: 10001,
        message: "添加任務成功",
        data: {
            missionid: "missionid_d4f555c0-aa38-11ea-b716-c335f1f3465d",
            date: "‘2020.6.8’",
            mission: "背單詞",
            flag: "0"
          }
        }
 */ 

@api

@api {method} path [title]
@api {get} /mission/add 添加任務
HTTP接口調用方法、路徑及名稱

@apiVersion

@apiVersion version
@apiVersion 1.0.0
api版本

@apiName

@apiName name
@apiName addMission
api 名稱

@apiGroup

@apiGroup name
@apiGroup Mission
api 分組

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiParam {String} date 添加時間
請求參數

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]
@apiSuccess {Number} code 結果標識
返回數據描述

@apiError

@apiError [(group)] [{type}] field [description]
接口失敗描述

@apiSuccessExample

@apiSuccessExample [{type}] [title] example
@apiSuccessExample Success-Response:{}
接口成功返回樣例

生成文檔

在根目錄下執行命令

apidoc -i routes/ -o apidoc/

讀取router文件夾下的注釋，輸出到apidoc文件夾下
點開apidoc文件夾中index.html會發現已經生成的漂亮的api文檔