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

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

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

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

1,引用 Swashbuckle.AspNetCore 包

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
});

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

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 });

效果如下:

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

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

2,添加1591禁用警告显示

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

1,给接口添加文本注释

显示效果如下:

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

显示效果如下:

3,响应状态码  文本注释

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

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

 

 

参考文档:

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

作者:PeterZhang
本文版权归作者和博客园共有,欢迎转载,但必须给出原文链接,并保留此段声明,否则保留追究法律责任的权利。
posted @ 2021-05-16 13:10  找.net工作(北京)  阅读(191)  评论(0编辑  收藏  举报