【C#編程最佳實踐 二十一】如何將接口生成接口文檔

如果接口過多可能需要把這些接口生成一個文檔來對外提供使用，這樣可以大幅的減少諮詢量，最近接的這個任務就是如此，所以如何快捷的將接口生成接口文檔就至關重要。我們選取的是docfx工具來進行生成：

1 下載docfx工具

可以通過github直接下載docfx，進入頁面後點擊下載最新版本即可：

2 添加環境變量

安裝好後，將docfx的安裝路徑添加系統的環境變量

3 初始化docfx

在docfx的安裝目錄，打開cmd命令窗口執行如下命令：docfx init -q初始化docfx，執行完之後，在當前目錄自動生成文件夾 docfx_project

4 創建和修改配置文件

在 docfx_project 創建好後，需要創建一個過濾文件filterConfig.yml用來過濾接口中不想對外暴露的部分
還需要修改一個配置文件docfx.json用來關聯需要生成文檔註釋的項目。

創建過濾文件filterConfig.yml

在docfx_project 目錄下直接創建即可：

過濾內容如下：Interface級別的過濾是整個provider過濾不展示，包括其下的所有方法，Member 級別表明過濾某個provider下的部分方法不展示

apiRules:
 - exclude:
    uidRegex: '^.*(IxxxProvider|IxxxProvider|IxxxProvider)$'
    type: Interface        
 - exclude:
    uidRegex:  ^.*IUserXXXProvider\.(GetUserName|GetUserAge|GetUserTime)
    type: Member 
 - exclude:
    uidRegex:  ^.*IDataXXXProvider\.(GetUserNameList)
    type: Member 

修改配置文件docfx.json

該文件用於指定真實的本地要生成接口文檔的項目路徑，只需修改頭部的指向路徑即可：例如當前真實路徑G:\MultiTenant\XXX.MultiTenantV3\XXX.MultiTenantV3.ServiceInterface\XXX.MultiTenantV3.ServiceInterface.csproj則files的路徑(項目真實地址)和cwd的相對路徑（項目相對於docfx的位置）分別爲：

"metadata": [
    {
      "src": [
        {
          "files": [
            "XXX.MultiTenantV3/XXX.MultiTenantV3.ServiceInterface/XXX.MultiTenantV3.ServiceInterface.csproj" , //接口地址
            "XXX.MultiTenantV3/XXX.MultiTenant.Model/XXX.MultiTenant.Model.csproj",  //接口依賴的Model
            "XXX.MultiTenantV3/XXX.MultiTenant.Model.OperationSDK/XXX.MultiTenant.ModelOperationSDK.csproj", //接口依賴的Model
          ],
		    "cwd": "../../MultiTenant/"
        }
      ],	  
      "dest": "api",
	  "filter": "filterConfig.yml",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],

5 生成相關文檔

在docfx_project 目錄下執行 CMD命令 ：docfx metadata生成對應的文檔：

生成後的文件會出現在api文件夾下：

6 進一步優化，手動區分Interface和Model

現在interface文件和Model文件混在一起，需要進一步區分這兩類文件：

• 將 yml文件分成兩類：Model、Interface，每個文件夾下 都需要包含 toc.yml和index.md 兩個文件，並刪除API目錄下的 .mainifest文件：
• 將對應的接口或model的yml文件分別放到兩個文件夾下，並且修改各自的toc.yml文件，保證該文件裏的內容和yml文件保持對應，也就是在Model的toc.yml刪除provider的項，反之亦然

在api層面下的toc.yml修改爲如下內容，用來定位它的子級目錄

在這裏插入代碼片 
- name: 數據接口文檔
  href: Interface/toc.yml
- name: 數據Model文檔
  href: Model/toc.yml

7 生成文檔

生成文檔需要兩步，首先執行CMD命令 ：docfx build，構建完成後，執行docfx serve _site，執行完成後即可通過站點 http://localhost:8080/查看效果，需要注意的是站點客戶端cmd要一直開着，才能看到