第二十六天：在 TeamCity 上显示 API 文件

昨天我们介绍了如何用 KDoc 语法标记程序码并用 Dokka 来产生 API 文件，今天我们要将产生 API 文件这个动作整合进 CI 流程里，让 TeamCity 每次在程序码库有变更、建置任务成功时，自动帮我们产生 API 文件。另外，笔者也希望能更进一步，不仅是自动产生出 API 文件，还能直接在 TeamCity 的 Build 详细页面浏览 API 文件！这将会用到 TeamCity 里 Report Tab 的功能。

设定产生 API 文件的 Build Step

首先我们要在原本的 Build Step 里增加一步，这一步就是执行 $./gradlew dokkaHtml 指令来产生 API 文件。设定方式很简单，首先进到专案 Build Configuration 里 Build Step 的设定。

按下 Add build step 按钮新增一个 Step，Runner Type 选 Gradle、Step name 输入 Generate API document、Gradle tasks 输入 dokkaHtml，其他保留预设值後按 Save 储存。

Artifact（成品）储存设定

在这边要注意一件事，虽然 Build Step 已经设定好会执行 dokkaHtml 指令产生 API 文件，但假如我们没有告诉 TeamCity 要把哪些东西存下来的话，这些专案原始码、产生出来的文件档案等通通都会在建置任务结束後删除。而这种因为建置任务而「产生」出来的档案（有可能是 Jar 档、有可能是 HTML 档）称为 Artifact（成品）。TeamCity 可以让我们设定一个 Artifact 的储存规则，这些档案就会在建置任务完成後以 Zip 压缩档的方式从 Agent 送回 TeamCity Server 储存。

回到专案的 Build Configuration 设定首页，选择左边侧边栏的 General Settings，设定页上的 Artifact paths 就是让我们设定要把专案结构底下的哪些资料夹需要存起来。其用的语法为：

+:<路径> => <档名>.zip

其中 +: 表示要包括後面接着的路径，<路径> 则是以专案根目录为基准的相对路径，=> 表示要输出，<档名> 是我们希望输出的档案名称，TeamCity 预设以 Zip 做压缩储存。昨天在使用 Dokka 输出 API 文件时，读者应该有发现预设的输出路径为 build/dokka/html，也就是说，我们的 Artifact path 要指到 html 这个资料夹，而我们就把 API 文件的档名设成 docs 吧，所以这边的设定就写成

+:build/dokka/html => docs.zip

完成後就按 Save 储存。

测试/下载 Artifact

我们先看能不能成功打包 Artifact。点击 Run 开始执行建置任务，建置完成後，我们可以看到在 Build 列表上最新一笔的最右边有一个 Artifact 的图示亮起来了。您可以直接点击图示观看 Artifact 有哪些、也可以直接下载。

另外也可以进到 Build 的详细页面，上方也有 Artifacts 页签可以看产生出来的成品是什麽。

将文件显示在 Report Tab

虽然 TeamCity 自动帮我们把 Artifact 产生出来很方便，但要看 API 文件时，还得自己下载下来、解压缩、在浏览器里打开网页。若是能直接在 TeamCity 里面看每一个 Build 产生出来的 API 文件是不是更方便呢？

这个需求我们可以靠 TeamCity 里 Report Tab 的功能，直接在 Build 里增加一个客制化的页签，直接在页签里显示 Artifact 里的 API 文件内容。

首先进到专案设定页，选择左边侧边栏的 Report Tabs 功能，这边可以设定两种 Report Tab，一种是针对每一个 Build 设定、一种是针对整个 Project 做设定。以我们目前的需求来说，我们想要看到「每一次」Build 完时的 API 文件，所以需要的是 Build Report Tab。

点一下画面上方 Create new build，在弹出式视窗里设定 Tab Title 为 API Docs，Start page 会需要以 <Artifact 名称>.zip!文件首页.html 的格式做设定。因为我们在上一步设定的 Artifact 压缩档名称为 docs.zip 而 API 文件首页 index.html，Start page 的设定就是 docs.zip!index.html，完成後按 Save 储存。

这时再回到 Build 详细页面，选择刚刚完成、有产生出 API 文件 Artifact 的那一次 Build，进入到 Build 详细页，就会看到刚刚设定的 API Docs 页签。点一下页签，TeamCity 会马上开始解压缩 docs.zip 并把 index.html 以 iframe 的方式显示在页签里，非常方便！

TeamCity 会很聪明的看该次 Build 有没有名为 docs.zip 的 Artifact，若没有的话则 API Docs 页签也不会显示。

小结

今天我们学会如何在 TeamCity 里依照需求新增一个 Report Tabs，让我们可以直接在每一次 Build 里直接浏览 API 文件。由於程序码会一直变更，API 文件也会跟着一直更新，所以可以看到每一个 Build 产生的 API 文件，会帮助我们了解并纪录 API 文件的变化。

不过，毕竟 API 文件通常是公开提供给使用者浏览的，我们也不会开放 TeamCity 的权限给一般使用者，所以若我们确定 Build 产生的 API 文件没问题後，就希望可以一键将 API 文件部署到网页主机上方便让所有人查看。这部份也希望可以由 TeamCity 为我们服务，也就是标准的 CD（Continuous Deployment），我们明天就来讨论这个主题！

参考资料

• Including Third-Party Reports in the Build Results