基于 abp vNext 和 .NET Core 开发博客项目 - 再说Swagger，分组、描述、小绿锁

时间  2020-05-23
标签 基于 abp vnext core 开发 博客 项目 再说 swagger 分组 描述 繁體版
原文   原文链接

在开始本篇正文以前，解决一个 @疯疯过 指出的错误，再次感谢指正。html

0

步骤以下：git

  • 删掉.Domain.Shared层中的项目引用，添加nuget依赖包Volo.Abp.Identity.Domain.Shared，可使用命令：Install-Package Volo.Abp.Identity.Domain.Shared
  • 在.Domain层中引用项目.Domain.Shared，在模块类中添加依赖typeof(MeowvBlogDomainSharedModule)
  • 将.EntityFrameworkCore层中的引用项目.Domain.Shared改为.Domain。

0

上一篇文章(http://www.javashuo.com/article/p-rtnsqrfg-kp.html)完成了对API返回模型的封装，紧接着我打算继续来折腾一下Swagger，以前的文章中已经简单用起了Swagger，本篇仍是围绕它让其发挥更高的更多的价值。github

当咱们的项目不断壮大，API持续增多，这时若是想要快速准肯定位到某个API可能不是那么容易，须要翻半天才能找对咱们的API。因而对Swagger API文档分组和详细的文档描述就有必要了，就本项目而言，博客系统能够分组为：博客前台接口、博客后台接口、其它公共接口、JWT认证受权接口。json

其中，博客后台组中的接口须要受权后才能够调用，须要受权那么就涉及到身份验证，在这里准备采用JWT(JSON WEB TOKEN)的方式进行。api

分组

对Swagger进行分组很简单，在.Swagger层中的扩展方法AddSwagger(this IServiceCollection services)中屡次调用options.SwaggerDoc(...)便可，像这样app

...
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "1.0.0",
        Title = "个人接口啊1",
        Description = "接口描述1"
    });
    options.SwaggerDoc("v2", new OpenApiInfo
    {
        Version = "1.0.0",
        Title = "个人接口啊2",
        Description = "接口描述2"
    });
    ...
...

不过这样显得有点low，而后能够转变一下思路使用遍历的方式进行。options.SwaggerDoc(...)接收两个参数：string name, OpenApiInfo info。ui

name：能够理解为当前分组的前缀；OpenApiInfo：有许多可配置的参数，在这里我只用到三个，Version、Title、Description。this

要注意，当在AddSwagger(...)中调用完后，还须要在咱们的扩展方法UseSwaggerUI(this IApplicationBuilder app)中options.SwaggerEndpoint()使用它，一样的也用遍历的方法。它接收的的参数：string url, string name。url

url：这里的url要与前面配置的name参数对应。spa

name：咱们自定义显示的分组名称。

因而能够直接在扩展方法中新建一个内部类：SwaggerApiInfo

internal class SwaggerApiInfo
        {
            /// <summary>
            /// URL前缀
            /// </summary>
            public string UrlPrefix { get; set; }

            /// <summary>
            /// 名称
            /// </summary>
            public string Name { get; set; }

            /// <summary>
            /// <see cref="Microsoft.OpenApi.Models.OpenApiInfo"/>
            /// </summary>
            public OpenApiInfo OpenApiInfo { get; set; }
        }

而后新建一个List<SwaggerApiInfo>手动为其初始化一些值。

...
       /// <summary>
        /// Swagger分组信息，将进行遍历使用
        /// </summary>
        private static readonly List<SwaggerApiInfo> ApiInfos = new List<SwaggerApiInfo>()
        {
            new SwaggerApiInfo
            {
                UrlPrefix = Grouping.GroupName_v1,
                Name = "博客前台接口",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = version,
                    Title = "阿星Plus - 博客前台接口",
                    Description = description
                }
            },
            new SwaggerApiInfo
            {
                UrlPrefix = Grouping.GroupName_v2,
                Name = "博客后台接口",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = version,
                    Title = "阿星Plus - 博客后台接口",
                    Description = description
                }
            },
            new SwaggerApiInfo
            {
                UrlPrefix = Grouping.GroupName_v3,
                Name = "通用公共接口",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = version,
                    Title = "阿星Plus - 通用公共接口",
                    Description = description
                }
            },
            new SwaggerApiInfo
            {
                UrlPrefix = Grouping.GroupName_v4,
                Name = "JWT受权接口",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = version,
                    Title = "阿星Plus - JWT受权接口",
                    Description = description
                }
            }
        };
...

version：咱们将其配置在appsettings.json中，作到动态能够修改。

//AppSettings.cs
...
        /// <summary>
        /// ApiVersion
        /// </summary>
        public static string ApiVersion => _config["ApiVersion"];
...

//appsettings.json
{
...
  "ApiVersion": "1.0.0"
...
}

description：由于屡次使用，就定义一个变量，内容自拟主要是一些介绍性的描述，将在Swagger界面进行显示。

UrlPrefix：分别为，v1,v2,v3,v4。在Domain.Shared层中为其定义好常量

//MeowvBlogConsts.cs
...
        /// <summary>
        /// 分组
        /// </summary>
        public static class Grouping
        {
            /// <summary>
            /// 博客前台接口组
            /// </summary>
            public const string GroupName_v1 = "v1";

            /// <summary>
            /// 博客后台接口组
            /// </summary>
            public const string GroupName_v2 = "v2";

            /// <summary>
            /// 其余通用接口组
            /// </summary>
            public const string GroupName_v3 = "v3";

            /// <summary>
            /// JWT受权接口组
            /// </summary>
            public const string GroupName_v4 = "v4";
        }
...

如今修改扩展方法AddSwagger(...)，遍历List<SwaggerApiInfo>。

...
        public static IServiceCollection AddSwagger(this IServiceCollection services)
        {
            return services.AddSwaggerGen(options =>
            {
                //options.SwaggerDoc("v1", new OpenApiInfo
                //{
                //    Version = "1.0.0",
                //    Title = "个人接口啊",
                //    Description = "接口描述"
                //});

                // 遍历并应用Swagger分组信息
                ApiInfos.ForEach(x =>
                {
                    options.SwaggerDoc(x.UrlPrefix, x.OpenApiInfo);
                });
                ...
            });
        }
...

在扩展方法UseSwaggerUI(...)使用，通用也须要遍历。

...
        // 遍历分组信息，生成Json
        ApiInfos.ForEach(x =>
        {
                options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
        });
...

细心的同窗能够发现，咱们前几篇文章打开Swagger文档的时候都是须要手动更改URL地址：.../swagger才能正确进入，其实Swagger是支持配置路由的。同时我们也将页面Title也给改了吧。看下面UseSwaggerUI(...)完整代码：

...
        /// <summary>
        /// UseSwaggerUI
        /// </summary>
        /// <param name="app"></param>
        public static void UseSwaggerUI(this IApplicationBuilder app)
        {
            app.UseSwaggerUI(options =>
            {
                // 遍历分组信息，生成Json
                ApiInfos.ForEach(x =>
                {
                    options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
                });

                // 模型的默认扩展深度，设置为 -1 彻底隐藏模型
                options.DefaultModelsExpandDepth(-1);
                // API文档仅展开标记
                options.DocExpansion(DocExpansion.List);
                // API前缀设置为空
                options.RoutePrefix = string.Empty;
                // API页面Title
                options.DocumentTitle = "😍接口文档 - 阿星Plus⭐⭐⭐";
            });
        }
...

options.DefaultModelsExpandDepth(-1);是模型的默认扩展深度，设置为 -1 彻底隐藏模型。

options.DocExpansion(DocExpansion.List);表明API文档仅展开标记，不默然展开全部接口，须要咱们手动去点击才展开，能够自行查看DocExpansion。

options.RoutePrefix = string.Empty;表明路由设置为空，直接打开页面就能够访问了。

options.DocumentTitle = "😍接口文档 - 阿星Plus⭐⭐⭐";是设置文档页面的标题的。

完成以上操做，在Controller中使用 Attribute：[ApiExplorerSettings(GroupName = ...)]指定是哪一个分组而后就能够愉快的使用了。

默认不指定的话就是所有都有，目前只有两个Controller，咱们将HelloWorldController设置成v3，BlogController设置成v1。

//HelloWorldController.cs
...
    [ApiExplorerSettings(GroupName = Grouping.GroupName_v3)]
    public class HelloWorldController : AbpController
    {
        ...
    }
...

//BlogController.cs
...
    [ApiExplorerSettings(GroupName = Grouping.GroupName_v1)]
    public class BlogController : AbpController
    {
        ...
    }
...

编译运行，打开咱们的Swagger文档看一下。

1

2

本身试着换切换一下分组试试吧，大功告成。​

描述

在Swagger文档中，默认只显示咱们的Controller的名称，其实他也是支持描述信息的，这是就须要咱们自行扩展了。在.Swagger层新建一个文件夹Filters，添加SwaggerDocumentFilter类来实现IDocumentFilter接口。

//SwaggerDocumentFilter.cs
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Collections.Generic;
using System.Linq;

namespace Meowv.Blog.Swagger.Filters
{
    /// <summary>
    /// 对应Controller的API文档描述信息
    /// </summary>
    public class SwaggerDocumentFilter : IDocumentFilter
    {
        public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
        {
            var tags = new List<OpenApiTag>
            {
                new OpenApiTag {
                    Name = "Blog",
                    Description = "我的博客相关接口",
                    ExternalDocs = new OpenApiExternalDocs { Description = "包含：文章/标签/分类/友链" }
                }
                new OpenApiTag {
                    Name = "HelloWorld",
                    Description = "通用公共接口",
                    ExternalDocs = new OpenApiExternalDocs { Description = "这里是一些通用的公共接口" }
                }
            };

            // 按照Name升序排序
            swaggerDoc.Tags = tags.OrderBy(x => x.Name).ToList();
        }
    }
}

实现Apply(...)方法后，使用Linq语法对文档排个序，而后最重要的使用这个Filter，在扩展方法AddSwagger(...)中使用

public static IServiceCollection AddSwagger(this IServiceCollection services)
        {
            return services.AddSwaggerGen(options =>
            {
                ...
                // 应用Controller的API文档描述信息
                options.DocumentFilter<SwaggerDocumentFilter>();
            });
        }

再打开Swagger文档看看效果。

3

ok，此时描述信息也出来了。

小绿锁

在Swagger文档中开启小绿锁是很是简单的，只需添加一个包：Swashbuckle.AspNetCore.Filters，直接使用命令安装：Install-Package Swashbuckle.AspNetCore.Filters

而后再扩展方法AddSwagger(this IServiceCollection services)中调用

public static IServiceCollection AddSwagger(this IServiceCollection services)
{
    return services.AddSwaggerGen(options =>
    {
        ...
        var security = new OpenApiSecurityScheme
        {
            Description = "JWT模式受权，请输入 Bearer {Token} 进行身份验证",
            Name = "Authorization",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey
        };
        options.AddSecurityDefinition("oauth2", security);
        options.AddSecurityRequirement(new OpenApiSecurityRequirement { { security, new List<string>() } });
        options.OperationFilter<AddResponseHeadersFilter>();
        options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
        options.OperationFilter<SecurityRequirementsOperationFilter>();
        ...
    });
}

以上便实现了在Swagger文档中显示小绿锁，咱们new的OpenApiSecurityScheme对象，具体参数你们能够自行看一下注释就明白具体含义。分别调用options.AddSecurityDefinition(...)、options.AddSecurityRequiremen(...)、options.OperationFilter(...)，编译运行，打开瞅瞅。

4

如今只是作了小绿锁的显示，可是并无实际意义，由于在.net core中还须要配置咱们的身份认证受权代码，才能具体发挥其真正的做用，因此目前咱们的api仍是处于裸奔状态，谁都能调用你的api，等你发现你写的文章都被别人删了，你都不知道为何。

实现JWT，将在下篇文章中详细说明，本篇到这里就结束了，咱们完善了Swagger文档，给接口加了分组、描述，还有小绿锁。老铁，你学会了吗？😁😁😁

开源地址：https://github.com/Meowv/Blog/tree/blog_tutorial

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程