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

# API 文件規範

API目前分兩大分類，一個是RESTful API，另一個則是一般SDK API。RESTful API遵循[OpenAPI格式](https://swagger.io/specification/)，SDK部分則是使用IDE文件產生工具去生成，最後統一使用docfx文件管理工具統一管理。

## 1.RESTful API

### a.使用工具
- Swagger

### b.輸出格式
- .md檔案

### c.規範細節
基本上就遵循[OpenAPI格式](https://swagger.io/specification/)，只要Code註解有寫好，使用Swagger會自動幫你產生。需涵蓋資料如下

- 1.功能名稱資訊 : 如 API 的版本、標題、描述
- 2.路徑 : API url, ex:POST/UploadImage
- 3.Header : Authentication
- 4.parameter : 每個 endpoint 可能需要的參數，如路徑參數、查詢參數、body 參數等。
- 5.Response : HTTP 回應碼，以及每個回應的內容格式和說明。
- 6.資料模型或物件(選填) : Dto Schema


## 2.SDK

### a.使用工具

- C# : docfx
- Java : 手寫marckdown (目前javadoc整合性低)

### b.輸出格式
- C# : .yaml
- Java : .md檔案

### c.規範細節
- 1.專案引入說明
- 2.功能名稱 : 函式名稱
- 3.描述 : 功能細節描述
- 4.Parameter參數 : 輸入參數
- 5.Return : 返回結果
- 6.Expection(建議填) : 例外事件
- 7.範例(選填)


目前Java版為手寫Marckdown，參考如下