---
# System prepended metadata

title: API 文件規ㄈ

---

###### 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 

![](https://hackmd.io/_uploads/r19M-EeJ6.png)


## 2.SDK

### a.使用工具

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

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

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

![](https://hackmd.io/_uploads/rynnIExk6.png)

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

![](https://hackmd.io/_uploads/B1KOwVl1T.png)


