欢迎光临
我的个人博客网站

.Net Core 3.x Api开发笔记 — Swagger(七)

Swagger 可以用来快速生成REST API文档

其他的不多说,该章节演示如何在 .Net Core Api中使用

在老的项目框架中使用该组件,可以参考另外一篇文章:在MVC项目中使用 Swagger API文档

1,引用 Swashbuckle.AspNetCore 包

.Net Core 3.x Api开发笔记 -- Swagger(七)

2,在 Startup 中进行注册 

services.AddSwaggerGen(c => {     c.SwaggerDoc("v1", new OpenApiInfo { Title = "NetCore.Api", Version = "v1" }); });

3,在 Configure(IApplicationBuilder app, IWebHostEnvironment env) 启用中间件

注意:下边的 v1 必须和上边的 v1相同,假如上边是 v2,下边相应的也要改成 v2

//启用中间件服务生成Swagger作为JSON终结点 app.UseSwagger(); //启用中间件服务对swagger-ui,指定Swagger JSON终结点 app.UseSwaggerUI(c => {     c.SwaggerEndpoint("/swagger/v1/swagger.json", "NetCore.Swagger v1");     c.RoutePrefix = string.Empty;   //表示直接 http://localhost:5000 即可显示 Swagger UI });

编辑并运行,整体效果如下:

.Net Core 3.x Api开发笔记 -- Swagger(七)

4,Swagger高级用法,使用Swagger为API文档增加中文说明信息

 1 //注册Swagger  2 services.AddSwaggerGen(c =>  3 {  4     c.SwaggerDoc("v1", new OpenApiInfo  5     {  6         Title = "NetCore.Swagger",  7         Version = "v1",  8         Description = "一个简单的 ASP.NET Core API",  9         Contact = new OpenApiContact 10         { 11             Name = "印度阿三", 12             Email = string.Empty, 13             Url = new Uri("https://www.cnblogs.com/peterzhang123/") 14         } 15     }); 16  17     // 为 Swagger JSON and UI设置xml文档注释路径 18     // 获取应用程序所在目录(绝对路径,不受工作目录影响,建议采用此方法获取路径) 19     // 此方式适用于Windows/Linux 平台 20     var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location); 21     var xmlPath = Path.Combine(basePath, "NetCore.Swagger.xml"); 22     c.IncludeXmlComments(xmlPath); 23  24 });

效果如下:

.Net Core 3.x Api开发笔记 -- Swagger(七)

为接口方法添加文本注释,

1,勾选XML文档文件,文件会自动生成

2,添加1591禁用警告显示

.Net Core 3.x Api开发笔记 -- Swagger(七)

对于 Linux 操作系统,会对xml文件名和路径区分大小写,可以在Starup中使用下边红框中的代码解决:

.Net Core 3.x Api开发笔记 -- Swagger(七)

1,给接口添加文本注释

.Net Core 3.x Api开发笔记 -- Swagger(七)

显示效果如下:

.Net Core 3.x Api开发笔记 -- Swagger(七)

2,使用 <remarks> </remarks>标签中可以使用:文本、JSON 或 XML

.Net Core 3.x Api开发笔记 -- Swagger(七)

显示效果如下:

.Net Core 3.x Api开发笔记 -- Swagger(七)

3,响应状态码  文本注释

[ProducesResponseType(201)] [ProducesResponseType(400)]

.Net Core 3.x Api开发笔记 -- Swagger(七)

将请求参数全部删除,然后调用接口,返回结果如下:

 .Net Core 3.x Api开发笔记 -- Swagger(七)

 

参考文档:

https://www.cnblogs.com/yilezhu/p/9241261.html

赞(0) 打赏
未经允许不得转载:张拓的天空 » .Net Core 3.x Api开发笔记 — Swagger(七)
分享到: 更多 (0)

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

专业的IT技术经验分享 更专业 更方便

联系我们本站主机

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏