• 當前位置:首頁 > IT技術 > Windows編程 > 正文

    API文檔生成工具
    2021-09-17 11:54:59

    相信大家對API文檔生成工具并不陌生,也有很多的工具可以供大家選擇,小編就來給大家介紹一款。

    apidoc 是一款根據代碼上的注釋自動生成接口文檔的工具,它支持多種語言,以下JavaScript示例;

    注釋需要按照 apidoc 官網注釋規則;

    1.全局安裝 apidoc

    npm install apidoc -g 

    2.寫注釋?

    以下是寫得比較完整的一個注釋

    /** * @apiDefine apiSuccess 成功統一返回參數 * @apiSuccess {String} code code * @apiSuccess {String} msg msg * @apiSuccess {Object} data config data * */
    /**
         * @api {get} /config config(接口名稱)
         * @apiGroup api
         * @apiName getConfig(該字段不影響文檔顯示)
         * @apiDescription (接口描述)2.9.3起新config接口
         * @apiVersion 2.2.2(接口版本)
         *
         * @apiHeader {String} system 系統
         * @apiHeader {String} version 版本號
         *
         * @apiHeaderExample {json} Header-Example:
         *     {
         *       "system": "ios",
         *       "version": "2.2.2"
         *     }
         *
         * @apiUse apiSuccess
         *
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *        "code": 0,
         *        "msg": "",
         *        "data": {
         *          "id": 111,
         *          "system": "ios",
         *          "version": "2.2.2",
         *          "status": "0"
         *        }
         *      }
         *
         * */

    3.添加配置文件 apidoc.json 文件

    {
      "name": "接口名稱",  "title":"文檔標題"  "version": "2.2.2",
      "description": "文檔描述",
      "url" : "http://qa.api.test.com/",      // api路徑的前綴
      "sampleUrl": "http://qa.api.test.com/", // 如果設置了此選項,則將顯示用于測試api方法(發送請求)的表單。
      "template": {
        "withCompare": true,
        "withGenerator": true
      }
    }

    4.輸入命令,生成文檔

    // apidoc -i 指定讀取源文件的目錄 -o 指定輸出文檔的目錄
    apidoc -i src/ -o apidoc/

    根據我命令,在項目里會生成 apidoc 文件夾,該文件夾下 index.html 就是接口文檔;

    5.(本步驟可自選) 在 package.json 文件設置 scripts,這樣就不用再記命令了,運行 npm run apidoc 文檔生成;

    apidoc 的 html 文件轉 markdown 文件 -- apidoc-markdown

    apidoc-markdown 是一個根據apidoc輸出文件直接生成markdown文件的工具。

    1.全局安裝

    npm install  apidoc-markdown -g

    2.運行命令

    // apidoc-markdown -p apidoc 文件夾路徑 -o md文件生成路徑 -t 使用模板路徑
    apidoc-markdown -p public/apidoc -o public/doc_markdown.md -t public/templates/default_cn.md

    以上沒有指定md的模板,默認使用其自帶的md模板文件,對于 apidoc 中 api_data.json 文件的有些字段無法識別,最終生成的md文件不完整;

    需要自行使用 EJS模板文件,然鵝我沒找到現成的支持 apidoc 轉 md 的模板文件,所以就把默認的模板文件稍微修改了一下;

    我在用默認的模板文件轉 md 時遇到了 可選 參數轉換問題,具體體現如下:

    轉后的 md 文件顯示:

    API文檔生成工具_Java開發

    apidoc api_data.json 文件 :

    API文檔生成工具_Java開發_02

    apidoc-markdown 默認模板文件 修改前:

    ### Headers
    | Name    | Type      | Description                          |
    |---------|-----------|--------------------------------------|
    <% sub.header.fields.Header.forEach(header => { -%>
    | <%- header.field %> | <%- header.type ? ``${header.type}`` : '' %> | <%- header.optional ? '**optional**' : '' %><%- header.description %> |
    <% }) // foreach parameter -%>
    <% } // if parameters -%>
    <% if (sub.header && sub.header.examples && sub.header.examples.length) { -%>

    apidoc-markdown 默認模板文件 修改后:

    ### Headers
    | Name    | Type      | Optional  | Description                          |
    |---------|-----------|-----------|--------------------------------------|
    <% sub.header.fields.Header.forEach(header => { -%>
    | <%- header.field %> | <%- header.type ? ``${header.type}`` : '' %> | <%- header.optional ? '可選' : '' %> | <%- header.description %> |
    <% }) // foreach parameter -%>
    <% } // if parameters -%>
    <% if (sub.header && sub.header.examples && sub.header.examples.length) { -%>

    修改后 md文件:

    API文檔生成工具_Java開發_03

    本文摘自 :https://blog.51cto.com/u

    開通會員,享受整站包年服務
    国产呦精品一区二区三区网站|久久www免费人咸|精品无码人妻一区二区|久99久热只有精品国产15|中文字幕亚洲无线码