网站的建设思路,seo优化怎么做,重庆公司网站,威海建设网站最好的总会在不经意间出现。“作为后端程序员#xff0c;免不了与前端同事对接API#xff0c; 一个书写良好的API设计文档可有效提高与前端对接的效率。为避免联调时来回撕逼#xff0c;今天我们聊一聊正确编写Swaager API文档的姿势。基础Swagger用法在ConfigureServices配… 最好的总会在不经意间出现。“作为后端程序员免不了与前端同事对接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 Taskbool AddHotmapAsync([FromBody] CreateHotmapInput createHotmapInput)
{var model ObjectMapper.MapCreateHotmapInput, Hotmap(createHotmapInput);model.ProfileId CurrentUser.TenantId;return await _hotmaps.InsertAsync(model)! null;
}
产生如图示SwaggerUIPost请求的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 namecreateHotmapInput/param
/// returns/returns
[Consumes(application/json)]
[Produces(text/plan)]
[ProducesResponseType(typeof(Boolean), 200)]
[HttpPost]
public async Taskbool AddHotmapAsync([FromBody] CreateHotmapInput createHotmapInput)
{var model ObjectMapper.MapCreateHotmapInput, 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]添加GenerateDocumentationFiletrue/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的预期输出内容、预期状态码内容自述格式工整前端同事再也不会追着你撕逼了
