###### tags: `文件規範` `Tool` `docfx`

# API文件規範 - SDK API 與 md file整合至docfx

紀錄如何從C#專案產生出SDK API文件，並整合至docfx。Java部分則是使用md file直接做整合

- C#
- Step1 : 使用docfx產生yaml格式
- Step2 : 整合至docfx處理
- Java
- Step1 : 手寫md file
- Step2 : 整合至docfx處理

## C# SDK API文件整合

### Step1:使用docfx產生yaml格式

請至此處下載Sample SDK [(請點我)](https://github.com/spyua/MSMQUtility/tree/feature-for-docfx-testing)。並至MSMQUtility\MQUtility路徑下，下docfx init指令

docfx init --quiet

此時docfx會產出檔案如下


接著請修改docfx.json，請貼下述json設定

<details>
<summary>Json設定</summary>

{
  "metadata": [
    {
      "src": [
        {
			"files": [ "**/*.csproj" ],
			"src": "../"
        }
      ],
      "dest": "api",
      "includePrivateMembers": false,
      "disableGitFeatures": false,
      "disableDefaultFilter": false,
      "noRestore": false,
      "namespaceLayout": "flattened",
      "memberLayout": "samePage",
      "allowCompilationErrors": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "output": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default",
      "modern"
    ],
    "postProcessors": [],
    "keepFileLink": false,
    "disableGitFeatures": false
  }
}

</details>

設定設好後，直接下編譯指令

docfx .\docfx.json

編譯訊息如下，編譯完後會有一個_site資料夾，API靜態網頁都會在此資料夾內


此時我們可以下serve指令，試跑一下看起來有無問題，指令如下

docfx serve _site


跑起網頁內容會如下


### Step2 : 整合至docfx處理

為了整合，基本上我們會要的是api下的檔案，檔案如下圖


我們可以將這些檔案搬至我們要整合目標的docfx文件專案。這邊稍微Demo，請到此處下載docfx文件專案[(請點我至Repo)](https://github.com/spyua/api-document-test)。下載完後，請到api-document-test\sdk\CSharp新增一個MSMQ資料夾，並將檔案貼過去，貼完後如下


然後修改一下api-document-test\sdk\CSharp下的toc.yml，如下

- name: Introduction
  href: intro.md
- name: GCP
  href: GCP/
- name: Interface
  href: Interface/
- name: MSMQ
  href: MSMQ/

然後下編譯指令，並跑起來，就可以看到SDK CSharp下會多了一個MSMQ的分頁如下



以上是簡易Demo，如何將專案的SDK API整合至Target docfx的簡易流程。

## Java SDK API文件整合

### Step1 : 手寫md file
### Step2 : 整合至docfx處理

繼上述例子，我們直接Demo如何新增md file，請至sdk\Java下新增一個Demo資料夾，並在資料夾下新增 intro.md 、 toc.yml與一個 demo.md，並貼下述內容

- demo.md (New API專案裡的某支API文件)

 # New API Document

- toc.yml (目錄導航)

 - name: Demo API
   href: demo.md

- intro.md (根頁內容)

 # API Project

新增完後，再去改sdk/java下的目錄導航設置

- name: Introduction
  href: intro.md
- name: GCP
  href: GCP/
- name: Demo
  href: Demo/

然後下編譯指令，並跑起來，就可以看到SDK Java下會多了一個Demo的分頁如下



以上為SDK API整合至目標docfx的流程使用範例說明