ASP.NET Core 接口文档解决方案(swagger)
api文档解决方案很多,先介绍我用过的两种方案:
比较项 | Swagger | Showdoc |
---|---|---|
官网 | 帮助说明--ShowDoc | |
知名度 | 较大、net6 官方推荐 | 国产 |
在线测试 | 支持 | 不支持 |
文档定义方式 | 注释为主 | 注释为主 |
生成过程 | 自动根据接口参数和返回类型生成相关说明。 | 接口文档的一切都需在注释中自定义。手写内容较多,但能使文档更清楚直观。 |
依赖和文档更新 | 依附于接口程序,共生。 | 可通过一些简单操作,实现一键快速更新。像是个单独网站。 |
下载分享 | 支持下载 | 支持下载。可分享指定接口,或整个项目接口,且支持网址密码分享。有成员概念。 |
个人目前偏爱 showdoc,虽然它不能在线测试以及需要编写较多的注释,但真的好用。参考:帮助说明--ShowDoc
Swagger 介绍
Swagger (OpenAPI) 是一个与语言无关的规范,用于描述 REST API。
简而言之:
- OpenAPI 是一种规范。
- Swagger 是一种使用 OpenAPI 规范的工具。 例如,OpenAPIGenerator 和 SwaggerUI。
Swagger UI 提供了基于 Web 的 UI,它使用生成的 OpenAPI 规范(json)提供有关服务的信息。Web UI 如下所示:
在net 6中的使用Swagger
入门教程
在ASP.NET Core中的使用步骤,参考(重要,请必读跟着做):
Get started with Swashbuckle and ASP.NET Core | Microsoft Docs
简单看看跟着操作下就好,适合入门了解,但挺鸡肋。
实际应用保姆级教程
先引用netget包:
Swashbuckle.AspNetCore
Swashbuckle.AspNetCore.Annotations
IGeekFan.AspNetCore.Knife4jUI
//这个提供更美观好用的页面,是一热心网友做的开源优质皮肤。
编辑项目文件
打开接口的项目文件,设置要生成接口文档描述:
<GenerateDocumentationFile>True</GenerateDocumentationFile> <DocumentationFile>D:\AMyProject\web-idasheng\WebApi\ApiDocs\WebApi.xml</DocumentationFile>
其中,DocumentationFile 节点的路径可自定义,这个路径很重要。
然后点击重新生成解决方案。这时会看到生成的该xml文件,然后选中右击,点击【属性】,在“复制到输出目录”项,选择【始终复制】。以便发布时能带上该文件。
注意:对接口入参或返回数据中,涉及到的模型类,要在他们所在的项目,也要进行上面这样的设置,以便接口文档自动应用相关属性的注释说明。
这些模型类,要加上属性的注释,后面它就是接口文档的字段说明。像这样:
设置分组
一个软件系统的接口文档有很多,需要分组(或分版本),以便管理和查看,这里可以先建一个分组信息类:
public class ApiGroupInfo { public const string 开发测试= "开发测试"; public const string 公开服务= "公开服务"; public const string 官网相关= "官网相关"; public const string 其它= "其它"; }
然后在每个控制器中应用分组标识,多个控制器可以共用一个分组,就像这样:
[Produces("application/json")] [ApiExplorerSettings(GroupName = ApiGroupInfo.公开服务)]
具体的方法,主要就是写注释啦,swagger根据注释信息,生成文档描述。大概是下面这么个形式:
/// <summary> /// 获取应用信息 /// </summary> /// <returns></returns> [HttpGet] public IActionResult GetAppInfo() { return new JsonResult(_sysConfig.AppInfo); } /// <summary> /// 获取中国传统色 /// </summary> /// <param name="key">访问key</param> /// <returns></returns> [HttpGet] [ProducesDefaultResponseType(typeof(IEnumerable<Public_CnColors>))] public async Task<string> GetCnColors(string key) { var data = await new BasicCRUD<Public_CnColors>().GetList(); return EachData.Success(data); } /// <summary> /// 获取中国传统色2 /// </summary> /// <param name="key"></param> /// <returns></returns> [HttpGet] public async Task<EachData<IEnumerable<Public_CnColors>>> GetCnColorsV2(string key) { var data = await new BasicCRUD<Public_CnColors>().GetList(); return EachData<IEnumerable<Public_CnColors>>.Success(data); }
服务注册
下面代码,根据上面提到的分组类,遍历每个组信息,以便在接口文档形成分组下拉菜单。
然后对前文设置的xml文档进行了使用。
最后还配置了jwt bearer 授权,以便接口调试时携带该信息。
#region 服务注册:接口文档Swagger services.AddEndpointsApiExplorer(); services.AddSwaggerGen(options => { var desc = "请熟读并背诵接口文档。 "; var constantProperties = typeof(ApiGroupInfo) .GetFields(BindingFlags.Public | BindingFlags.Static) .ToArray(); foreach (var field in constantProperties) { options.SwaggerDoc(field.Name, new OpenApiInfo { Version = field.Name, Title = field.Name, Description = desc }); } var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlApiPath = Path.Combine(AppContext.BaseDirectory, $"ApiDocs/{Assembly.GetExecutingAssembly().GetName().Name}.xml"); var xmlEntityPath = Path.Combine(AppContext.BaseDirectory, "ApiDocs/Data.Entity.xml"); var xmlDtoPath = Path.Combine(AppContext.BaseDirectory, "ApiDocs/Data.Dto.xml"); options.IncludeXmlComments(xmlApiPath, true); options.IncludeXmlComments(xmlEntityPath, true); options.IncludeXmlComments(xmlDtoPath, true); options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme { Description = "Value: Bearer {token}", Name = "Authorization", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey, Scheme = "Bearer", BearerFormat = "JWT" }); options.AddSecurityRequirement(new OpenApiSecurityRequirement() { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" },Scheme = "oauth2",Name = "Bearer",In = ParameterLocation.Header, },new List<string>() } }); }); #endregion
中间件配置
if (app.Environment.IsDevelopment()) { app.UseDeveloperExceptionPage(); app.UseSwagger(); //app.UseSwaggerUI();//使用swagger默认的皮肤样式 app.UseKnife4UI(c => { c.RoutePrefix = String.Empty ; // serve the UI at root var constantProperties = typeof(ApiGroupInfo) .GetFields(BindingFlags.Public | BindingFlags.Static) .ToArray(); foreach (var field in constantProperties) { c.SwaggerEndpoint($"/swagger/{field.Name}/swagger.json", $"{field.Name}"); } }); }
这样,它就基本OK了,注意事项:
- 对接口action,最好标注
[HttpGet]
[HttpPost]
等 - 如果你的action返回类型是string,但其实是返回的是某个类型,那需要对action应用
[ProducesDefaultResponseType(typeof(Product))]
这个特性,来自动生成对设置类型的字段描述(来自注释)。
运行查看
至此,基本完成了,F5运行,路径定位到根目录,查看效果如下:
查看分组、在线测试,都还挺方便:
ShowDoc (推荐)
Showdoc简介,https://www.showdoc.com.cn/help/1385767280275683
使用程序注释自动生成API文档 https://www.showdoc.com.cn/page/741656402509783
优点:
- 使用简单,在接口程序无需做任何代码配置。完全可自定义请求参数、返回参数、返回数据示例。
- 可生成带访问密码的共享连接。
- 可转化成Word文档。
- 免费。(5人以下团队免费)。
- 接口文档不依赖接口站点程序。可以自建showdoc服务站点或在官网自建接口文档项目。
缺点:
- 高度依赖方法注释,每个请求参数或返回参数都需要写清楚。
- 另外暂时无法通过文档直接请求测试接口。
更新于:2023.5.19
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 没有源码,如何修改代码逻辑?
· PowerShell开发游戏 · 打蜜蜂
· 在鹅厂做java开发是什么体验
· WPF到Web的无缝过渡:英雄联盟客户端的OpenSilver迁移实战