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

在最先本篇正文之前,解决一个 @疯疯过 指出的错误,再次谢谢指正。

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

步骤如下:

  • 删掉.Domain.Shared层中的项目引用,添加nuget依赖包Volo.Abp.Identity.Domain.Shared,可以使用下令:Install-Package Volo.Abp.Identity.Domain.Shared
  • .Domain层中引用项目.Domain.Shared,在模块类中添加依赖typeof(MeowvBlogDomainSharedModule)
  • .EntityFrameworkCore层中的引用项目.Domain.Shared改成.Domain

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

上一篇文章(https://www.cnblogs.com/meowv/p/12924409.html)完成了对API返回模子的封装,紧接着我计划继续来折腾一下Swagger,之前的文章中已经简朴用起了Swagger,本篇照样围绕它让其施展更高的更多的价值。

当我们的项目不停壮大,API连续增多,这时若是想要快速准确定位到某个API可能不是那么容易,需要翻半天才气找对我们的API。于是对Swagger API文档分组和详细的文档形貌就有必要了,就本项目而言,博客系统可以分组为:博客前台接口、博客后台接口、其它公共接口、JWT认证授权接口。

其中,博客后台组中的接口需要授权后才可以挪用,需要授权那么就涉及到身份验证,在这里准备接纳JWT(JSON WEB TOKEN)的方式举行。

分组

对Swagger举行分组很简朴,在.Swagger层中的扩展方式AddSwagger(this IServiceCollection services)中多次挪用options.SwaggerDoc(...)即可,像这样

...
    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

name:可以理解为当前分组的前缀;OpenApiInfo:有许多可设置的参数,在这里我只用到三个,VersionTitleDescription

要注意,当在AddSwagger(...)中挪用完后,还需要在我们的扩展方式UseSwaggerUI(this IApplicationBuilder app)options.SwaggerEndpoint()使用它,同样的也用遍历的方式。它吸收的的参数:string url, string name

url:这里的url要与前面设置的name参数对应。

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(...)完整代码:

微软 Build 大会发布大量开发工具与服务!编码、协作、发布,如丝般顺滑

...
        /// <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文档看一下。

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

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

自己试着换切换一下分组试试吧,大功告成。​

形貌

在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文档看看效果。

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

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("JWT", 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(...),编译运行,打开瞅瞅。

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

现在只是做了小绿锁的显示,然则并没有实际意义,由于在.net core中还需要设置我们的身份认证授权代码,才气详细施展其真正的作用,以是现在我们的api照样处于裸奔状态,谁都能挪用你的api,等你发现你写的文章都被别人删了,你都不知道为什么。

实现JWT,将在下篇文章中详细说明,本篇到这里就竣事了,我们完善了Swagger文档,给接口加了分组、形貌,另有小绿锁。老铁,你学会了吗?

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

原创文章,作者:28qn新闻网,如若转载,请注明出处:http://www.28qn.com/archives/11012.html