###### tags: `API`

# API文件和模擬工具

[TOC]

簡介
===

## 為什麼需要API文件
- 開發需求來了，雙方要有溝通的文件。
- 前後端需要同時開工，前端可利用文件產生模擬。

## API文件工具
- [Atom](https://atom.io/)
好用的文件編輯工具
- [HackMD](https://hackmd.io)
超好用的文件編輯工具
- [API Blueprint](https://apiblueprint.org/)
一種API描述語言，可藉由`Atom`編輯`APIB`
- [Aglio](https://github.com/danielgtaylor/aglio)
API文件渲染工具，可將`MD`渲染成美化的`HTML`
- [Swagger](https://swagger.io/)
可在 `ASP.NET CORE`中安裝
- [SwaggerHub](https://swagger.io/tools/swaggerhub/)
可使用雲端服務(SaaS)或付費下載地端服務(On-Premise)

## API模擬工具
- [Prism](https://github.com/stoplightio/prism)
可利用`JSON`產生模擬
- [Drakov](https://github.com/Aconex/drakov)
可利用`MD`產生模擬
- [SwaggerHub API Auto Mocking](https://support.smartbear.com/swaggerhub/docs/integrations/api-auto-mocking.html)
雲端API模擬服務，需手動匯入或連接公共的`JSON`
- [Mock Service Worker](https://mswjs.io/)
相依在專案中，讓開發、測試、除錯一次到位

詳細介紹
===

## Atom
參考文件: [API Blueprint - 建立 API 文件的好工具](https://naurudao.blogspot.com/2016/02/api-blueprint-api.html)
1) 使用軟體
下載 Atom 來編輯 MD 檔案，可按 CTRL+SHIFT+M 開啟即時預覽。

## HackMD

## API Blueprint

## Aglio
1) 安裝套件

npm install -g aglio

2) 藉由MD輸出HTML

aglio -i api.md -o api.html

[下圖範例原始碼](https://hackmd.io/mJBUvBBvTwmLniuigQzCyg)

## Swagger

## SwaggerHub
1) 申請: 可用GitHub登入，或以Email申請，並填入公司名稱及個人電話
2) 啟動 : 可匯入JSON檔案或Swagger JSON所在的URL

## Prism
1) 安裝套件

npm install -g @stoplight/prism-cli

2) 啟動模擬

prism mock swagger.json


:::warning
注意 :zap:
啟動 Mock Server ，若出現 Invalid security scheme used，則有下列兩種方法，即可順利啟動：
1. 在Authorization加入任意值的Bearer Token。
2. 將JSON檔案裡各個API的Security刪除，畢竟是模擬，不會真實連線資料庫，所以可以暫不考慮API權限。
:::

## Drakov
參考文件: [使用Api-blueprint文件建立mock server](https://codertw.com/%E7%A8%8B%E5%BC%8F%E8%AA%9E%E8%A8%80/187976/)
1) 安裝套件

npm install -g drakov

2) 啟動模擬

drakov –f api.md -p 3000


:::warning
注意 :zap:
啟動 Mock Server 時drakov會檢查檔案語法，若出現Error: the use of carriage return(s) '\r' in source data isn't currently supported，則可使用Notepad++，開啟編輯，換行格式，轉換成UNIX格式，即可順利啟動。
:::

## SwaggerHub API Auto Mocking
啟動Mock Server：進入swaggerHub主頁面後，點選app進入(例如下圖為wms-api)，再點選左上方app名稱開啟下拉選單，再點選Integrations，接著點選Add New Integrations，再從下拉選單中選擇API Auto Mocking，填上名稱即可完成並啟動。

1) 新增API Auto Mocking

2) 介面右方就會出現Base URL: `https://virtserver.swaggerhub.com/<owner>/<project>/1.0.0`

3) 即可從外部Call mocking server的api，並獲得模擬數據

## Mock Service Worker
[官方範例](https://github.com/mswjs/examples)
React
- REST API with React
- GraphQL API with React (Apollo)

Angular
- REST API with Angular

在`ASP.NET CORE`專案中加入Swagger
===

## Swashbuckle
參考文件: [Swashbuckle](https://docs.microsoft.com/zh-tw/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio)
1) 安裝套件

Install-Package Swashbuckle.AspNetCore

2) 新增程式碼

在 Startup.ConfigureServices 方法中，註冊所需的 Swagger 服務：

public void ConfigureServices(IServiceCollection services)
{
    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}

在 Startup.Configure 方法中，啟用中介軟體為產生的 Swagger 規格和 SwaggerUI 提供服務：

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

3) 開啟介面
檢視 Swagger UI: `http://localhost:<port>/swagger`
檢視 Swagger 規格: `http://localhost:<port>/swagger/v1/swagger.json`

## NSwag
參考文件: [NSwag](https://docs.microsoft.com/zh-tw/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-5.0&tabs=visual-studio)
1) 安裝套件

Install-Package NSwag.AspNetCore

2) 新增程式碼

在 Startup.ConfigureServices 方法中，註冊所需的 Swagger 服務：

public void ConfigureServices(IServiceCollection services)
{
    // Register the Swagger services
    services.AddSwaggerDocument();
}

在 Startup.Configure 方法中，啟用中介軟體為產生的 Swagger 規格和 SwaggerUI 提供服務：

public void Configure(IApplicationBuilder app)
{
    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();
}

3) 開啟介面
檢視 Swagger UI: `http://localhost:<port>/swagger`
檢視 Swagger 規格: `http://localhost:<port>/swagger/v1/swagger.json`

工具關聯和比較表
===

| | API Blueprint | Swagger | SwaggerHub |
| --------------------- | :--------------: | :----------: | :----------------: |
| **編輯器(Editor)** | HackMD 或 Atom | Codegen | Swagger Editor |
| **網頁輸出(HTML)** | Aglio | Swagger UI | Swagger UI |
| **模擬(Mock server)** | Drakov | Prism | API Auto Mocking |

| API Blueprint | 描述 |
| ------------- | ---------------------------------------------------------------- |
| **優點** | 1) 可自行運用Markdown語法編輯文件<br>2) 利用HackMD可免費團隊協作 |
| **缺點** | 1) 沒有藉由程式碼自動產生文件的工具 |

| Swagger | 描述 |
| ------- | ---------------------------------------------------------------------------- |
| **優點** | 1) 可利用程式碼自動產生文件(Codegen)<br>2) 可直接在Swagger UI頁面手動測試API |
| **缺點** | 1) 模擬仍需下載JSON檔案後，在本地執行 |

| SwaggerHub | 描述 |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| **優點** | 1) 可雲端託管或本地部署(On-Premise)<br>2) 可授予不同人員不同編輯或閱讀權限<br>3) 管理多個Swagger來源(利用對外的URL) |
| **缺點** | 1) 進階功能需付費 |