Apidoc的安裝和使用簡介

1、apidoc是什麼？

apidoc是一個可以将源代碼中的注釋直接生成api接口文檔的工具，它支援各種不同的注釋風格，可以在各種語言中使用。

具體見官網介紹：apidoc官網

2、apidoc的安裝

第一步：由于apidoc依賴node.js的包管理工具npm進行安裝，是以安裝apidoc之前要先安裝node.js。node.js下載下傳

第二步：在指令行輸入：

npm install -g apidoc
           

再輸入：

apidoc -h
           

出現相關幫助資訊，說明安裝成功可以使用了

apidoc的使用

在指定檔案的目錄下打開指令行

，執行apidoc，便可以就可以自動生成一個doc文檔。

index.html

就是生成的api接口檔案。

注意：

1、在生成檔案之前，要在該目錄下添加一個apidoc.json檔案，格式如下：

{
    "name":"接口文檔名稱",
    "version":"版本号",
    "title":"這裡是頁面導航标題",
    "url":"接口連結"
}
 

           

2、如果要在接口檔案中添加頭檔案，則apidoc.json格式如下：

{
   "name":"接口文檔名稱",
    "version":"版本号",
    "title":"這裡是頁面導航标題",
    "url":"接口連結"，
    "header": {
        "title": "接口說明",
        "filename": "header.md"
    }
}
           

header.md

檔案同樣放在指定檔案目錄下

3、常用代碼（具體細節見官網）

1、 @api {method} path [title]

Name	Description
method	請求的方法，例如：post、get、put……
path	請求路徑
title	标題，通常用于導航和文章開頭

2、@apiName name

Name	Description
name	唯一的方法名，主要作用： 當某接口有不同的版本時使用，可以被區分

3、@apiGroup name

Name	Description
name	分組名，用于導航欄中

4、@apiDescription text

Name	Description
text	描述

5、@apiVersion version

Name	Description
version	版本号(major.minor.patch)

6、@apiParam [(group)] [{type}] [description]

Name	Description
(group)	一個分組名，把所有的參數分成一組
{type}	參數的資料類型
description	描述

7、@apiSuccess [(group)] [{type}] field [description]

Name	Description
(group)	一個分組名，把所有的參數分成一組
{type}	參數的資料類型
description	描述