昨天我們介紹了如何用 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