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

  • A+
所属分类：.NET技术
摘要

Swagger 可以用来快速生成REST API文档其他的不多说，该章节演示如何在 .Net Core Api中使用
便宜好用的国外VPS推荐

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

便宜好用的国外VPS推荐