最好的總會在不經意間出現。

“

作為后端程序員，免不了與前端同事對接API， 一個書寫良好的API設計文檔可有效提高與前端對接的效率。

為避免聯調時來回撕逼，今天我們聊一聊正確編寫Swaager API文檔的姿勢。

基礎Swagger用法

在ConfigureServices配置Swagger文檔,在Configure啟用中間件

?//?Install-Package?Swashbuckle.AspNetCore?略?services.AddSwaggerGen(options?=>{options.SwaggerDoc("v1",?new?OpenApiInfo?{?Title?=?"EAP?API",?Version?=?"v1"?});});????? ---app.UseSwagger(); app.UseSwaggerUI(options?=> {options.SwaggerEndpoint("/swagger/v1/swagger.json",?"EAP?API"); });

應用會在/Swagger頁面加載最基礎的API文檔。

以一個最簡單的Post請求為例，細數這最基礎Swagger文檔的弊病：

[HttpPost] public?async?Task<bool>?AddHotmapAsync([FromBody]?CreateHotmapInput?createHotmapInput) {var?model?=?ObjectMapper.Map<CreateHotmapInput,?Hotmap>(createHotmapInput);model.ProfileId?=?CurrentUser.TenantId;return?await?_hotmaps.InsertAsync(model)!=?null; }

產生如圖示SwaggerUI：

Post請求的Payload字段過于復雜，竟不給前端傳值example？

沒有約定請求的媒體類型，前端會不會給你另外一個surprise?

API 文檔沒有指示響應的媒體類型，前端以哪種姿勢接收？

API文檔沒有指示響應的預期輸出內容、狀態碼，前端會不會抓狂？

下文就來根治這些頑疾， 書寫一個自述性、優雅的API文檔。

Swagger最佳實踐

三下五除二，給出示例：

///?<summary> ///?添加熱力圖 ///?</summary> ///?<remarks> ///?Sample?request: ///?``` ///??POST?/hotmap ///??{ ///??????"displayName":?"演示名稱1", ///??????"matchRule":?0, ///??????"matchCondition":?"https://www.cnblogs.com/JulianHuang/", ///??????"targetUrl":?"https://www.cnblogs.com/JulianHuang/", ///??????"versions":?[ ///??????{ ///?????????"versionName":?"ver2020", ///?????????"startDate":?"2020-12-13T10:03:09", ///?????????"endDate":?"2020-12-13T10:03:09", ///??????????"offlinePageUrl":?"3fa85f64-5717-4562-b3fc-2c963f66afa6",??//??沒有綁定圖片和離線網頁的對應屬性傳?null ///??????????"pictureUrl":?"3fa85f64-5717-4562-b3fc-2c963f66afa6", ///??????????"createDate":?"2020-12-13T10:03:09" ///??????} ///????] ///??} ///``` ///?</remarks> ///?<param?name="createHotmapInput"></param> ///?<returns></returns> [Consumes("application/json")] [Produces("text/plan")] [ProducesResponseType(typeof(Boolean),?200)] [HttpPost] public?async?Task<bool>?AddHotmapAsync([FromBody]?CreateHotmapInput?createHotmapInput) {var?model?=?ObjectMapper.Map<CreateHotmapInput,?Hotmap>(createHotmapInput);model.ProfileId?=?CurrentUser.TenantId;return?await?_hotmaps.InsertAsync(model)!=null; }

通過給API添加XML注釋：remarks

“

注意如果注釋內容包含代碼，可以使用Markdown的代碼語法```,在注釋里面優雅顯示代碼。

通過Consumes,Produces特性指示action接收和返回的數據類型，也就是媒體類型。

“

Consumes、Produces是指示請求/響應支持的content-type的過濾器，位于Microsoft.AspNetCore.Mvc命名空間下。

通過ProducesResponseType特性指示API響應的預期內容、狀態碼

API文檔顯示如下：

這樣的Swagger文檔才正確表達了后端程序員的內心輸出。

---

在Swagger文檔上顯示注釋

生成XML文檔文件

在項目上[右鍵]-[屬性]-[生成標簽頁]-[勾選XML文檔文件]；

或者直接在項目csproj文件--[PropertyGroup]添加

<GenerateDocumentationFile>true</GenerateDocumentationFile>

在AddSwaggerGen方法添加下行，啟用注釋文件

//?Set?the?comments?path?for?the?Swagger?JSON?and?UI. var?xmlFile?=?$"{this.GetType().Assembly.GetName().Name}.xml"; var?xmlPath?=?Path.Combine(AppContext.BaseDirectory,?xmlFile); opt.IncludeXmlComments(xmlPath); “

這里啰嗦一下，如果是Abp Vnext解決方案(API是定義在HttpApi項目/Application項目)，若我們要為Abp Vnext解決方案加載帶xml注釋的Swagger Json，需要更改xmlFile為特定HttpApi.xml或applicaiton.xml。

以上就是小碼甲總結的書寫Swagger文檔的優雅姿勢：?

• 編寫API 傳值example

• 約束請求/響應 支持的媒體類型

• 指示API的預期輸出內容、預期狀態碼

內容自述，格式工整，前端同事再也不會追著你撕逼了！

總結

以上是生活随笔為你收集整理的Oh my God, Swagger API文档竟然可以这样写？的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。