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

# API文件規範 - Web Swagger API整合至docfx

紀錄如何將專案的API從Swagger產出至docfx，流程如下

- Step1 : 從Swagger Export出json檔案
- Step2 : 將Export的json轉成yaml格式
- Step3 : 使用widdershins tool將yaml轉成md file
- Step4 : 將md file整合進docfx


## Step1:從Swagger export Json檔案

Export json方法有很多種，直接一點的直接從你的Swagger頁面Export，他Exprot的格式會如下

<details>
<summary>Web API Json(From swagger)</summary>

{
    "openapi": "3.0.1",
    "info": {
        "title": "WebApplication1",
        "version": "1.0"
    },
    "paths": {
        "/WeatherForecast": {
            "get": {
                "tags": [
                    "WeatherForecast"
                ],
                "operationId": "GetWeatherForecast",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/WeatherForecast"
                                    }
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/WeatherForecast"
                                    }
                                }
                            },
                            "text/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/WeatherForecast"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "WeatherForecast": {
                "type": "object",
                "properties": {
                    "date": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "temperatureC": {
                        "type": "integer",
                        "format": "int32"
                    },
                    "temperatureF": {
                        "type": "integer",
                        "format": "int32",
                        "readOnly": true
                    },
                    "summary": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "additionalProperties": false
            }
        }
    }
}

</details>

## Step2:將Export的json轉成yaml格式

接著你可以用現有工具將他轉成yaml格式，這邊推薦使用[線上現有工具網站(點我)](https://codebeautify.org/json-to-yaml)。轉出來格式如下

<details>
<summary>Web API yaml</summary>

openapi: 3.0.1
info:
  title: WebApplication1
  version: '1.0'
paths:
  /WeatherForecast:
    get:
      tags:
        - WeatherForecast
      operationId: GetWeatherForecast
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WeatherForecast'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WeatherForecast'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WeatherForecast'
components:
  schemas:
    WeatherForecast:
      type: object
      properties:
        date:
          type: string
          format: date-time
        temperatureC:
          type: integer
          format: int32
        temperatureF:
          type: integer
          format: int32
          readOnly: true
        summary:
          type: string
          nullable: true
      additionalProperties: false

</details>

## Step3 : 使用widdershins tool將yaml轉成md file
請把yaml下載下來，或是自建yaml檔案把轉出來的yaml code貼過去。 接著要使用wiffershins建置md file。未安裝的可以使用npm安裝，指令如下

npm install -g widdershins

接著針對你的yaml下下述指令，demo.yaml為你從json轉成yaml的檔案，demo.md是你的輸出file

widdershins .\demo.yaml -o demo.md

他就會轉成如下圖，這邊我用Markdown Preview示意demo.md的一部分內容


## Step4 : 將md file整合進docfx

最後會稍微麻煩一點，因為這關係如何使用docfx，docfx詳細使用可參照[此篇(點我)](https://stingy-sky-248.notion.site/docfx-fc175ecfff9644eabe82abc1830d2dc2?pvs=4)。這篇快速帶如何整合處理。請先Clone此專案[(連結點我)](https://github.com/spyua/api-document-test)。

接著請將你的demo.md放置此資料夾下


並修改同資料夾的yaml

- name: Upload Image
  href: upload-image.md
- name: Member Account
  href: member.md
- name: Demo
  href: demo.md

接著下指令編譯

docfx docfx.json


Test Run結果如下

docfx serve _site


最後在做重新靜態網頁部屬即可