.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文档增加中文说明信息

//注册Swagger
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "NetCore.Swagger",
        Version = "v1",
        Description = "一个简单的 ASP.NET Core API",
        Contact = new OpenApiContact
        {
            Name = "印度阿三",
            Email = string.Empty,
            Url = new Uri("https://www.cnblogs.com/peterzhang123/")
        }
    });

    // 为 Swagger JSON and UI设置xml文档注释路径
    // 获取应用程序所在目录（绝对路径，不受工作目录影响，建议采用此方法获取路径）
    // 此方式适用于Windows/Linux 平台
    var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
    var xmlPath = Path.Combine(basePath, "NetCore.Swagger.xml");
    c.IncludeXmlComments(xmlPath);

});

效果如下：

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

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