示例采用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文檔

通過上述介紹，相信大家對API接口文檔生成工具已經有所了解，Java的知識點有很多，大家要不斷的學習，才能掌握前沿的Java技術。