基于 abp vnext 和 .net core 开发博客项目 -凯发k8官方网

基于 abp vnext 和 .net core 开发博客项目 - 再说swagger，分组、描述、小绿锁

https://github.com/meowv/blog

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

图片

步骤如下：

删掉.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：有许多可配置的参数，在这里我只用到三个，version、title、description。

要注意，当在addswagger(…)中调用完后，还需要在我们的扩展方法useswaggerui(this iapplicationbuilder app)中options.swaggerendpoint()使用它，同样的也用遍历的方法。它接收的的参数：string url, string name。

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

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

于是可以直接在扩展方法中新建一个内部类：swaggerapiinfo

internal class swaggerapiinfo{///

/// url前缀///

public string urlprefix { get; set; }///

/// 名称///

public string name { get; set; }///

/// ///

public openapiinfo openapiinfo { get; set; }}

然后新建一个list手动为其初始化一些值。

…
///
/// swagger分组信息，将进行遍历使用
///
private static readonly list apiinfos = new list()
{
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
…
///
/// apiversion
///
public static string apiversion => _config[“apiversion”];
…

//appsettings.json
{
…
“apiversion”: “1.0.0”
…
}
description：因为多次使用，就定义一个变量，内容自拟主要是一些介绍性的描述，将在swagger界面进行显示。

urlprefix：分别为，v1,v2,v3,v4。在domain.shared层中为其定义好常量

//meowvblogconsts.cs
…
///
/// 分组
///
public static class grouping
{
///
/// 博客前台接口组
///
public const string groupname_v1 = “v1”;

///

/// 博客后台接口组///

public const string groupname_v2 = "v2";///

/// 其他通用接口组///

public const string groupname_v3 = "v3";///

/// jwt授权接口组///

public const string groupname_v4 = "v4";}

…
现在修改扩展方法addswagger(…)，遍历list。

…
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(…)完整代码：

…
///
/// useswaggerui
///
///
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页面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
{
///
/// 对应controller的api文档描述信息
///
public class swaggerdocumentfilter : idocumentfilter
{
public void apply(openapidocument swaggerdoc, documentfiltercontext context)
{
var tags = new list
{
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();});}

再打开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() } });
options.operationfilter();
options.operationfilter();
options.operationfilter();
…
});
}
以上便实现了在swagger文档中显示小绿锁，我们new的openapisecurityscheme对象，具体参数大家可以自行看一下注释就明白具体含义。分别调用options.addsecuritydefinition(…)、options.addsecurityrequiremen(…)、options.operationfilter(…)，编译运行，打开瞅瞅。

图片

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

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

开源地址：https://github.com/meowv/blog/tree/blog_tutorial

总结

以上是凯发k8官方网为你收集整理的基于 abp vnext 和 .net core 开发博客项目 - 再说swagger，分组、描述、小绿锁的全部内容，希望文章能够帮你解决所遇到的问题。

如果觉得凯发k8官方网网站内容还不错，欢迎将凯发k8官方网推荐给好友。