基础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。
