基于 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


上一篇文章完成了对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(...)使用,通用也需要遍历。

...// 遍历分组信息,生成JsonApiInfos.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 =>{// 遍历分组信息,生成JsonApiInfos.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页面Titleoptions.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文档看一下。

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

描述

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

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

现在只是做了小绿锁的显示,但是并没有实际意义,因为在.net core中还需要配置我们的身份认证授权代码,才能具体发挥其真正的作用,所以目前我们的api还是处于裸奔状态,谁都能调用你的api,等你发现你写的文章都被别人删了,你都不知道为什么。

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

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

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/309746.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

[C++11]独占的智能指针unique_ptr的初始化和使用

std::unique_ptr 是一个独占型的智能指针&#xff0c;它不允许其他的智能指针共享其内部的指针&#xff0c;可以通过它的构造函数初始化一个独占智能指针对象&#xff0c;但是不允许通过赋值将一个 unique_ptr 赋值给另一个 unique_ptr。std::unique_ptr 不允许复制&#xff0c…

Abp v2.8.0发布 路线图

ABP框架和ABP商业版v2.8已经发布.这篇文章将涵盖这些发布中的新增内容和项目的中期路线图.ABP框架2.8有哪些新增内容?你可在GitHub的发行说明中看到所有的变更.这篇博客只包括重要的一些功能/变更.SignalR集成包我们已经发布了一个新的包用来集成SignalR到基于ABP框架应用程序…

贵州大学计算机专业的导师是谁,贵州大学计算机科学与信息学院导师介绍:王以松...

贵州大学计算机科学与信息学院导师介绍&#xff1a;王以松王以松&#xff0c;男&#xff0c;副教授&#xff0c;硕士研究生导师。主要研究方向&#xff1a;人工智能(知识表示与推理、逻辑程序设计)&#xff0c;语义网络等。 Em作者佚名次阅读2012-01-04王以松&#xff0c;男&am…

BitArray虽好,但请不要滥用,又一次线上内存暴增排查

一&#xff1a;背景1. 讲故事前天写了一篇大内存排查在园子里挺火&#xff0c;这是做自媒体最开心的事拉&#xff0c;干脆再来一篇满足大家胃口&#xff0c;上个月我写了一篇博客提到过使用bitmap对原来的List<CustomerID>进行高强度压缩&#xff0c;将原来的List内存压缩…

[翻译]用于.NET Core的Windows窗体设计器发布

本文由微信公众号《开发者精选资讯》翻译首发&#xff0c;转载请注明来源今天我们很高兴地宣布&#xff0c;.NET Core 项目的 Windows 窗体设计器现在可以在 Visual Studio 2019 16.6 版中作为预览使用&#xff01;我们在 Visual Studio 16.7 预览版 1 中也提供了更新的设计器版…

【视频回放与课件】零基础入门AI开发

今天上午&#xff0c;受广州图书馆邀请&#xff0c;在第一讲《零代码上手人工智能》的基础上&#xff0c;以《零基础入门AI开发》为主题&#xff0c;分四步解锁人工智能学习的概念与开发工具&#xff0c;让您在一小时内轻松掌握人工智能开发要领。本次课程内容主要包括&#xf…

Redis背后的故事

导语Redis已成为世界上最受欢迎的数据库之一&#xff0c;但当初正是因为Sanfilippo对数据库“缺乏经验”&#xff0c;使他敢于打破“良好”数据库工程的各种神圣规则&#xff0c;创建了Redis。正文如果Redis之父萨尔瓦多桑菲利波普&#xff08;Salvatore Sanfilippo&#xff09…

C++实现AOE网中的关键路径算法(邻接表存储)

代码如下: #include <iostream> #include <stack> #include <string> using namespace std; const int N 10010; using vnodeType int;typedef struct Node {int adj;int tw;//弧的时间权值Node *next; }Node;typedef struct Vnode {vnodeType v;//存储图…

Minimal Square CodeForces - 1360A(简单思维和图形判断)

题意&#xff1a; 给你两个大小一样的&#xff0c;边长为a&#xff0c;b的矩形将其放入一个正方形里&#xff0c;问怎样放可以使正方形面积最小&#xff08;要求正方形边和矩形边平行&#xff09; 题目&#xff1a; Find the minimum area of a square land on which you ca…

基于 abp vNext 和 .NET Core 开发博客项目 - 接入GitHub,用JWT保护你的API

上一篇文章再次把Swagger的使用进行了讲解&#xff0c;完成了对Swagger的分组、描述和开启小绿锁以进行身份的认证授权&#xff0c;那么本篇就来说说身份认证授权。开始之前先搞清楚几个概念&#xff0c;请注意认证与授权是不同的意思&#xff0c;简单理解&#xff1a;认证&…

第五站 使用winHex利器加深理解数据页

这篇我来介绍一个winhex利器&#xff0c;这个工具网上有介绍&#xff0c;用途大着呢&#xff0c;可以用来玩数据修复&#xff0c;恢复删除文件等等。。。。它能够将一个file解析成hex形式&#xff0c;这样你就可以对hex进行修改&#xff0c;然后你就可以看到修复后的结果&#…

法国 计算机金融 大学,捷报|GPA3.0,计算机转申金融,斩获法国顶级商学院录取!...

原标题&#xff1a;捷报|GPA3.0&#xff0c;计算机转申金融&#xff0c;斩获法国顶级商学院录取&#xff01;NutsCongratulationsNuts北大学员,GPA3.0计算机转申金融&#xff0c;斩获✨ 全法排名第二ESSEC金融录取✨OfferESSEC法国著名学府埃塞克高等商学院(cole suprieure des…

是小厂全栈好,还是大厂专业工程师好?

作者&#xff1a;邹溪源&#xff0c;长沙资深互联网从业者&#xff0c;架构师社区特邀嘉宾&#xff01;一在博客园中使用小公司大公司进行搜索&#xff0c;列入的搜索记录长达50页。虽然完全命中关键词的文章也许并不多&#xff0c;但这或许也能体现出这个话题的热门程度。今天…