###### 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) 進階功能需付費 |