Singo'Sky

ASP.NETCore使用Swagger

发表于 本文字数： 4k 阅读时长 ≈ 4 分钟

什么是swagger

swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。

简单来讲，使用swagger能够自动生成友好的在线接口文档，并且支持接口测试，其好处：

  • 对后端人员：减少了编写接口后还要花费时间同步更新接口文档，且与前端沟通的时间成本。
  • 对前端人员：能够直观的快速的看到接口，并且进行在线测试，方便了调试调用接口，不用因接口问题频繁与后端沟通。

简单使用

步骤

框架.net3.1默认没有swagger，需要自己弄，以下简单写步骤

  1. nuget安装

    1
    Install-Package Swashbuckle.AspNetCore

  2. Startup.cs文件引入命名空间

    1
    2
    using Swashbuckle.AspNetCore.Swagger;
    using Microsoft.OpenApi.Models;

  3. 将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中

    1
    2
    3
    4
    5
    //注册Swagger生成器，定义一个和多个Swagger 文档
    services.AddSwaggerGen(c =>
    {
         c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });

  4. 在 Startup.Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务

    1
    2
    3
    4
    5
    6
    7
    //启用中间件服务生成Swagger作为JSON终结点
    app.UseSwagger();
    //启用中间件服务对swagger-ui，指定Swagger JSON终结点
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

  5. 此时启动项目就可通过http://localhost:<port>/swagger地址访问Swagger UI浏览API文档。

    也可通过http://localhost:<port>/swagger/v1/swagger.json地址访问生成的描述终结点的json文档。

  6. 如果要想通过http://localhost:<port>/就访问Swagger UI，修改启用中间件SwaggerUI的方法UseSwaggerUI，把RoutePrefix 属性设置为空字符串。

    1
    2
    3
    4
    5
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.RoutePrefix = string.Empty;
    });

添加版本控制

步骤

  1. 添加API枚举类型

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    /// <summary>
    /// 版本控制
    /// </summary>
    public enum ApiVersion
    {
        /// <summary>
        /// v1版本
        /// </summary>
        V1 = 1,
        /// <summary>
        /// v2版本
        /// </summary>
        V2 = 2
          
    }

  2. 修改Startup.ConfigureServices里注册Swagger的代码

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    //注册Swagger生成器，定义一个和多个Swagger 文档
    services.AddSwaggerGen(c =>
    {
        //遍历版本信息
        typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
        {
            c.SwaggerDoc(version, new OpenApiInfo
            {
                Version = version, //版本号
                Title = $"My API {version}", //标题
                Description = $"My ASP.NET Core Web API {version}", //描述
                //上面三项最后设置，下面的三项可以不用
                TermsOfService = new Uri("https://example.com/terms"), //服务条款
                Contact = new OpenApiContact
                {
                    Name = "Singo", //联系人
                    Email = string.Empty,  //邮箱
                    Url = new Uri("https://github.com/hushitong"),//网站
                },
                License = new OpenApiLicense
                {
                    Name = "Use under LICX", //协议
                    Url = new Uri("https://example.com/license"), //协议地址
                }
            });
        });
    });

  3. 修改Startup.Configure 里启用中间件的设置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    //启用中间件服务生成Swagger作为JSON终结点
    app.UseSwagger();
    //启用中间件服务对swagger-ui，指定Swagger JSON终结点
    app.UseSwaggerUI(c =>
    {
        c.RoutePrefix = string.Empty;

        typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
        {
            //描述终结点的json文档
            c.SwaggerEndpoint($"/swagger/{version}/swagger.json", version);
            //设置为none可折叠所有方法
            c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None);
        });
    });

  4. 然后就是使用ApiExplorerSettingsAttribute标注各个版本Controller，然后修改路由信息

    原来的标注为

    1
    [ApiExplorerSettings(GroupName = nameof(ApiVersion.V1))]

    后来的根据需要标注

    1
    [ApiExplorerSettings(GroupName = nameof(ApiVersion.V2))]

  5. 启动后就可以通过右上角的下拉框选择需要的版本进行测试了

注意

有关版本控制实际有很多办法，如：可以查看Net Core WebApi几种版本控制对比

添加JWT支持

  1. 修改Startup.ConfigureServices里注册Swagger的代码

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    //注册Swagger生成器，定义一个和多个Swagger 文档
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

        #region 添加JWT支持
        c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
        {
            Description = "在下框中输入请求头中需要添加Jwt授权Token：Bearer Token",
            Name = "Authorization", //设置其key名，请求时会添加上，默认使用Authorization名
            In = ParameterLocation.Header, //在请求头添加JWT Token
            Type = SecuritySchemeType.ApiKey,
            BearerFormat = "JWT",
            Scheme = "Bearer"
        });

        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
                },
                new string[] { }
            }
        });
        #endregion
    });

  2. 运行进入SeaggerUI页面，可以看到在页面右上角多了一个Authorize按钮，点击在value框可以填入bear <your jwt string>，以后请求头都会带上Authorization: bear <your jwt string>

    SwaggerWithJWT