apidoc接口文檔生成

簡介：apidoc是一個輕量級的在線REST接口文檔生成系統，支持多種主流語言，包括Java、C、C#、PHP和Javascript等。使用者僅需要按照要求書寫相關注釋，就可以生成可讀性好、界面美觀的在線接口文檔。

1、安裝

apidoc是基於nodeJs平台，在安裝apidoc之前，需要先安裝nodeJs和npm（安裝步驟省略）。

進入命令行，輸入npm install apidoc -g安裝

2、使用

先介紹一下apidoc中的重要命令和參數：

apidoc的命令格式如下：　　apidoc 參數

參數    描述
-f    選擇要解析的文件，支持正則表達式。-f參數可以使用多次，多個表達式可以對應不同的-f。如：apidoc -f ".*\.js$" -f ".*\\.ts$"
-i    選擇源代碼所在的位置。如：apidoc -i myapp/
-o    選擇生成的目標文件所在的位置。如：apidoc -o apidoc/
-t    為生成文件選擇模板，可以創建和使用自定義的模板。（筆者注：目前為止，筆者還沒有使用過這個參數）
-h    跟絕大多數命令一樣，這個參數可以打印出幫助文檔

以下為本地測試目錄

 

1. apidoc.json：apidoc的項目級配置文件，它必須位於整個工程目錄頂層。
2. Demo1.java：用於演示的demo源文件，它可以位於整個工程目錄的頂層目錄及其子目錄下。apidoc會搜索整個工程目錄選擇所有可能的源文件。

 apidoc.json

常用配置

配置名    描述
name    工程名。如果該字段不存在，則apidoc會嘗試通過package.json（apidoc頂層配置文件）來生成
version    工程文檔的版本號。如果該字段不存在，則apidoc會嘗試通過package.json（apidoc頂層配置文件）來生成
description    工程詳細描述。如果該字段不存在，則apidoc會嘗試通過package.json（apidoc頂層配置文件）來生成
title    文檔標題，顯示在文檔界面的最上方
url    整個api url的前綴，接下來的所有接口url都會加上這個前綴
sampleUrl    api示例的url前綴。如果設置了這個值，則界面中顯示請求表單，可以用於測試接口
header    
title    文檔頭（header）的連接錨點名
filename    文檔頭所使用的文件
footer    
title    文檔尾（footer）的連接錨點名
filename    文檔尾所使用的文件
order    接口的排列順序list，如果不指定，則由apidoc自行確定

示例：

{
  "name": "apidoc測試", 
  "version": "1.0.0",
  "description": "這是一個簡單的apidoc的demo",
  "title": "demo",
  "url" : "https://api.github.com/v1"
}

Demo1.java

　常用注解：

@api 定義API的請求方法、路徑和名字
@apiDescription 定義API的描述
@apiGroup 定義API的分組
@apiParam 定義API的參數
@apiParamExample 參數請求的事例
@apiVersion 版本
@apiErrorExample API錯誤示例
@apiSuccessExample API正常示例

示例

/**
     * @apiGroup Product
     * @api {GET} /product/{id}  查詢一個產品
     * @apiDescription 指定產品id , 刪除產品的全部信息，包括關聯的schema
     * @apiParam {String} id 產品id(必填*)
     * @apiSuccessExample SuccessExample
     * HTTP/1.1 200
     * {
     * id: 'xxx',
     * modelId: 'xxxxx',
     * name: 'xxx',
     * intro: 'xxxx'
     * }
     * @apiErrorExample ErrorExample
     * HTTP/1.1 600
     * 具體的異常信息
     */
    @GetMapping("/{id}")
    public Product getOneProduct(@PathVariable String id)
    {
        return productServ.findOne(id);
    }

3、運行

進入apidoc目錄，打開命令行：輸入 apidoc -i src/ -o apidoc/

 

打開index.html就可以看到了