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

文章目录

- 一、前言
- 二、实践技巧
- - 2.1 显示中文注释
  - - 1）基础配置
    - 2）添加范例
    - 3）添加响应结果
  - 2.2 提供全局`Api`元数据
  - 2.3 生成多个`Api`文档
  - - 1）配置节点
    - 2）添加控制器

一、前言

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

二、实践技巧 2.1 显示中文注释

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

1）基础配置

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

 
     true
     $(NoWarn);1591

修改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添加如下内容：

/// 
/// 天气预报服务
/// 
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    ......
    /// 
    /// 获取天气预报信息
    /// 
    /// 天气预报结果
    [HttpGet]
    public IEnumerable 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添加注释：

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

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



    
        swaggertestbase
    
    
        
            
            天气预报服务
            
        
        
            
            获取天气预报信息
            
            天气预报结果
        
        
            
            天气预报实体
            
        
        
            
            日期
            
        
        
            
            温度-摄氏度
            
        
        
            
            温度-华摄氏度
            
        
        
            
            描述

运行项目，Api文档如下：

2）添加范例

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

/// 
/// 天气预报服务
/// 
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    ......
    /// 
    /// 获取天气预报信息
    /// 
    /// 天气预报结果
    /// 
    /// 测试范例：
    /// 
    ///     GET /WeatherForecast/
    ///     
    /// 
    [HttpGet]
    public IEnumerable 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();
    }
    ......
}

运行效果：

3）添加响应结果

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

/// 
/// 天气预报服务
/// 
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    ......
    /// 
    /// 获取天气预报信息
    /// 
    /// 天气预报结果
    /// 
    /// 测试范例：
    /// 
    ///     GET /WeatherForecast/
    ///     
    /// 
    /// 
    /// 请求成功并且服务器创建了新的资源
    /// 请求失败，错误请求
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [HttpGet]
    public IEnumerable 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();
    }
    ......
}

运行效果：

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文档运行效果如下：

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）添加控制器

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

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

运行效果如下：
v1

v2

由于篇幅较长，剩余内容请查看笔者b篇。

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

.Net相关栏目本月热门文章