Asp.Net Core遇到Swagger(二)-Swashbuckle技巧a篇

关关长语

已于 2023-09-06 15:00:47 修改

阅读量2k

点赞数 5

分类专栏： Asp.Net Core # Swagger 文章标签： .net swagger2

于 2021-08-21 01:13:01 首次发布

本文链接：https://blog.csdn.net/qq_28806349/article/details/119833814

版权

Asp.Net Core 同时被 2 个专栏收录

7 篇文章 1 订阅

订阅专栏

Swagger

6 篇文章 0 订阅

订阅专栏

本文档详细介绍了如何使用Swashbuckle在ASP.NET Core项目中实现中文注释显示、添加示例以及处理响应结果。包括配置XML注释文件、使用Remarks添加范例、定义响应状态码，以及设置全局API元数据和生成多个API文档的方法。此外，还展示了如何通过ApiExplorerSettings进行API分组。

摘要由CSDN通过智能技术生成

文章目录

一、前言

上篇Swashbuckle(一)，主要是讲解的Core中swagger对应框架Swashbuckle的基础使用，本篇文章讲解基于Swashbuckle的进一步实践应用操作和配置。

blog-jrz-swagger-header

二、实践技巧

2.1 显示中文注释

Api文档从Xml注释文档中获取描述信息，将基本的信息展示到Swagger UI文档中。

1）基础配置

编辑项目xxxx.csproj文件，添加如下节点：

 <PropertyGroup>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <NoWarn>$(NoWarn);1591</NoWarn>
 </PropertyGroup>

修改Configure函数中SwaggerGen中间件服务配置，用于加载xml注释文件配置；

public void ConfigureServices(IServiceCollection services)
{
    ..........
    services.AddSwaggerGen(
        options => {
            //获取当前执行程序集名称+.xml,作为实际xml注释文件名称
            string filename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            //拼接路径-路径间隔符由系统决定
            string path = System.IO.Path.Combine(System.AppContext.BaseDirectory, filename);
            //添加xml注释文件到swaggergen中用于生成api json
            options.IncludeXmlComments(path);
        }
        );
    .........
}

为案例项目中的控制器下Action添加如下内容：

/// <summary>
/// 天气预报服务
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    ......
    /// <summary>
    /// 获取天气预报信息
    /// </summary>
    /// <returns>天气预报结果</returns>
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        var rng = new Random();
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        })
        .ToArray();
    }
    ......
}

实体类WeatherForecast添加注释：

/// <summary>
/// 天气预报实体
/// </summary>
public class WeatherForecast
{
    /// <summary>
    /// 日期
    /// </summary>
    public DateTime Date { get; set; }
    /// <summary>
    /// 温度-摄氏度
    /// </summary>
    public int TemperatureC { get; set; }
    /// <summary>
    /// 温度-华摄氏度
    /// </summary>
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    /// <summary>
    /// 描述
    /// </summary>
    public string Summary { get; set; }
}

重新生成项目后，可以在当前项目的bin/debug文件夹下，查看到对应的xxxx.xml；

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>swaggertestbase</name>
    </assembly>
    <members>
        <member name="T:swaggertestbase.Controllers.WeatherForecastController">
            <summary>
            天气预报服务
            </summary>
        </member>
        <member name="M:swaggertestbase.Controllers.WeatherForecastController.Get">
            <summary>
            获取天气预报信息
            </summary>
            <returns>天气预报结果</returns>
        </member>
        <member name="T:swaggertestbase.WeatherForecast">
            <summary>
            天气预报实体
            </summary>
        </member>
        <member name="P:swaggertestbase.WeatherForecast.Date">
            <summary>
            日期
            </summary>
        </member>
        <member name="P:swaggertestbase.WeatherForecast.TemperatureC">
            <summary>
            温度-摄氏度
            </summary>
        </member>
        <member name="P:swaggertestbase.WeatherForecast.TemperatureF">
            <summary>
            温度-华摄氏度
            </summary>
        </member>
        <member name="P:swaggertestbase.WeatherForecast.Summary">
            <summary>
            描述
            </summary>
        </member>
    </members>
</doc>

运行项目，Api文档如下：
Swagger-json-swashxmlcommit

2）添加范例

注释中使用Remarks标记进行范例添加，

/// <summary>
/// 天气预报服务
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    ......
    /// <summary>
    /// 获取天气预报信息
    /// </summary>
    /// <returns>天气预报结果</returns>
    /// <remarks>
    /// 测试范例：
    /// 
    ///     GET /WeatherForecast/
    ///     
    /// </remarks>
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        var rng = new Random();
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        })
        .ToArray();
    }
    ......
}

运行效果： Swagger-json-swashgenxmlremarks

3）添加响应结果

添加response节点进行，响应结果的处理，

/// <summary>
/// 天气预报服务
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    ......
    /// <summary>
    /// 获取天气预报信息
    /// </summary>
    /// <returns>天气预报结果</returns>
    /// <remarks>
    /// 测试范例：
    /// 
    ///     GET /WeatherForecast/
    ///     
    /// </remarks>
    /// </remarks>
    /// <response code="201">请求成功并且服务器创建了新的资源</response>
    /// <response code="400">请求失败，错误请求</response>
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        var rng = new Random();
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        })
        .ToArray();
    }
    ......
}

运行效果：
Swagger-json-xmlresponse

2.2 提供全局`Api`元数据

Api文档的基础信息，包含文档名称、文档版本、描述信息、团队信息、联系方式、颁发说明。

public void ConfigureServices(IServiceCollection services)
{
    ..........
    services.AddSwaggerGen(
        options => {
            ......
                    #region 文档元数据
                    options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo {
                        Title = "ggcy doc",
                        Version = "v1",
                        Description = "this is ggcy doc",
                        TermsOfService = new System.Uri("https://github.budbud.cn"),
                        Contact = new Microsoft.OpenApi.Models.OpenApiContact { 
                            Name ="ggcy",
                            Email = "ggcy@email.com",
                            Url = new System.Uri("https://github.budbud.cn")
                        }
                    });
                    #endregion 
            ......
        }
        );
    .........
}

Api文档运行效果如下：
Swagger-json-swashgenapimeta

2.3 生成多个`Api`文档

对于Api进行文档分组，在系统运行时，生成多个Api文档，需要在服务注册时进行配置，在SwaggerGen扩展函数中进行配置，

public void ConfigureServices(IServiceCollection services)
{
    ..........
    services.AddSwaggerGen(
        options => {
            ......
                    #region 文档元数据
                    options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo {
                        Title = "ggcy doc",
                        Version = "v1",
                        Description = "this is ggcy doc",
                        TermsOfService = new System.Uri("https://github.budbud.cn"),
                        Contact = new Microsoft.OpenApi.Models.OpenApiContact { 
                            Name ="ggcy",
                            Email = "ggcy@email.com",
                            Url = new System.Uri("https://github.budbud.cn")
                        }
                    });
            		//添加分组v2
                    options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo
                    {
                        Title = "ggcy v2",
                        Version = "v2"
                    });
                    #endregion
            ......
        }
        );
    .........
}

1）配置节点

配置中间件SwaggerUI中对应的请求节点，

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
..........
    #region Swagger中间件相关
    //添加swagger配置，并启动中间件
    app.UseSwagger(options =>
        {
            options.RouteTemplate = "{documentName}/swaggerapi.json";
        }
    );
    //启用Swagger-ui中间件，并配置swagger json的请求终节点
    app.UseSwaggerUI(options => {
        options.RoutePrefix = "api-docs";
        options.SwaggerEndpoint("/v1/swaggerapi.json","ggcy docs");
        //设置swagger-ui对应的节点v2
        options.SwaggerEndpoint("/v2/swaggerapi.json","ggcy v2");
    });
    #endregion
...........
}

2）添加控制器

Swagger-json-swashaddcontroller

设定名称为ValuesController，设置ApiExplorerSettings(GroupName = "v2")，其中ApiExplorerSettings既可以作用于控制器类，又可以作用于对应的Action，

[ApiController]
[Route("api/[controller]")]
[ApiExplorerSettings(GroupName ="v2")]
public class ValuesController : ControllerBase
{
    /// <summary>
    /// 获取数据信息
    /// </summary>
    /// <returns>返回结果</returns>
    [HttpGet]
    public IEnumerable<string> Get()
    {
        return new string[] {
            "O","B","C"
        };
    }
}