【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.MultiTenant.ServiceInterface/XXX.MultiTenant.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要一直开着，才能看到