1. 程式人生 > >企業分布式微服務雲SpringCloud SpringBoot mybatis (二十六)集成apidoc

企業分布式微服務雲SpringCloud SpringBoot mybatis (二十六)集成apidoc

命令 準備工作 目錄 說明 在外 多文件 cimage ref 簡單

一、apidoc簡介

apidoc通過在你代碼的註釋來生成api文檔的。它對代碼沒有侵入性,只需要你寫好相關的註釋即可,並且它僅通過寫簡單的配置就可以生成高顏值的api接口頁面。它基於node.js,所以你需要安裝node.js環境。node.js安裝,點擊這裏。這裏就不介紹。

二、準備工作

安裝完node.js安裝api.doc,它的項目源碼:https://github.com/apidoc/apidoc 。

通過命令安裝:

npm install apidoc -g

  

三、註釋怎麽寫

  • @api
    @api {method} path [title]
    
    method:請求方法,
    path:請求路徑 
    title(可選):標題
    

      

  • @apiDescription
    @apiDescription text
    text說明
    

      

  • @apiError
    @apiError [(group)] [{type}] field [description]
    
    (group)(可選):參數將以這個名稱分組,不設置的話,默認是Error 4xx 
    {type}(可選):返回值類型,例如:{Boolean}, {Number}, {String}, {Object}, {String[]} 
    field:返回值字段名稱 
    descriptionoptional(可選):返回值字段說明
    

      

  • @apiGroup
    @apiGroup name
    name:組名稱,也是導航的標題
    

      

    更多註釋,參見官方文檔:http://apidocjs.com/#params

    四、寫給栗子

    首先寫配置文件

    在項目的主目錄新建一個apidoc.json文件:

    {
      "name": "example",
      "version": "0.1.0",
      "description": "A basic apiDoc example"
    }
    

      

    更多配置參考:http://apidocjs.com/#configuration

    寫個註釋:

       /**
         * @api {POST} /register 註冊用戶
         * @apiGroup Users
         * @apiVersion 0.0.1
         * @apiDescription 用於註冊用戶
         * @apiParam {String} account 用戶賬戶名
         * @apiParam {String} password 密碼
         * @apiParam {String} mobile 手機號
         * @apiParam {int} vip = 0  是否註冊Vip身份 0 普通用戶 1 Vip用戶
         * @apiParam {String} [recommend] 邀請碼
         * @apiParamExample {json} 請求樣例:
         *                ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
         * @apiSuccess (200) {String} msg 信息
         * @apiSuccess (200) {int} code 0 代表無錯誤 1代表有錯誤
         * @apiSuccessExample {json} 返回樣例:
         *                {"code":"0","msg":"註冊成功"}
         */
    

      

    用apidoc命令生成文檔界面

    先cd到工程的外層目錄,並在外層目建個輸出文檔的目錄,我建的是docapi。

    輸命令:

    apidoc -i chapter4/ -o apidoc/
    

      

    -i 輸入目錄 -o 輸出目錄

    chapter4是我的工程名。

    可以看到在apidoc目錄生成了很多文件:

    技術分享圖片

    打開index.html,可以看到文檔頁面:

    技術分享圖片

  • 技術分享圖片源碼來源

企業分布式微服務雲SpringCloud SpringBoot mybatis (二十六)集成apidoc