---
# System prepended metadata

title: API文件和模擬工具
tags: [API]

---

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

## HackMD


## API Blueprint


## Aglio
![](https://i.imgur.com/nraSdl3.png)
1) 安裝套件
``` powershell
npm install -g aglio
```
2) 藉由MD輸出HTML
``` powershell
aglio -i api.md -o api.html
```
[下圖範例原始碼](https://hackmd.io/mJBUvBBvTwmLniuigQzCyg)
![](https://i.imgur.com/jzEW6gJ.png)

## Swagger


## SwaggerHub
1) 申請: 可用GitHub登入，或以Email申請，並填入公司名稱及個人電話 
2) 啟動 : 可匯入JSON檔案或Swagger JSON所在的URL
![](https://i.imgur.com/6FWj63o.png)


## Prism
1) 安裝套件
``` powershell
npm install -g @stoplight/prism-cli
```
2) 啟動模擬
``` powershell
prism mock swagger.json
```
![](https://i.imgur.com/I0O8wcU.png)

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

## Drakov
![](https://i.imgur.com/QzcsvEo.png)
參考文件: [使用Api-blueprint文件建立mock server](https://codertw.com/%E7%A8%8B%E5%BC%8F%E8%AA%9E%E8%A8%80/187976/)
1) 安裝套件
``` powershell
npm install -g drakov
```
2) 啟動模擬
``` powershell
drakov –f api.md -p 3000
```
![](https://i.imgur.com/6U2QtoF.png)

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

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

1) 新增API Auto Mocking 
![](https://i.imgur.com/294jyEO.png)

2) 介面右方就會出現Base URL: `https://virtserver.swaggerhub.com/<owner>/<project>/1.0.0`
![](https://i.imgur.com/Wi8EMRh.png)

3) 即可從外部Call mocking server的api，並獲得模擬數據 
![](https://i.imgur.com/ke4xTU5.png)

## 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) 安裝套件
``` powershell
Install-Package Swashbuckle.AspNetCore
```
2) 新增程式碼

在 Startup.ConfigureServices 方法中，註冊所需的 Swagger 服務：
``` csharp=
public void ConfigureServices(IServiceCollection services)
{
    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}
```

在 Startup.Configure 方法中，啟用中介軟體為產生的 Swagger 規格和 SwaggerUI 提供服務：
    
``` csharp=
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) 安裝套件
``` powershell
Install-Package NSwag.AspNetCore
```
2) 新增程式碼

在 Startup.ConfigureServices 方法中，註冊所需的 Swagger 服務：
``` csharp=
public void ConfigureServices(IServiceCollection services)
{
    // Register the Swagger services
    services.AddSwaggerDocument();
}
```

在 Startup.Configure 方法中，啟用中介軟體為產生的 Swagger 規格和 SwaggerUI 提供服務：
    
``` csharp=
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) 進階功能需付費                                                                                        |
