【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要一直开着,才能看到

展开阅读全文

没有更多推荐了,返回首页

©️2019 CSDN 皮肤主题: 点我我会动 设计师: 上身试试
应支付0元
点击重新获取
扫码支付

支付成功即可阅读