凯发k8天生赢家一触即发

从壹开始前后端分离【 .net core2.0 vue2.0 】框架之四 || swagger的使用 3.2 -凯发k8天生赢家一触即发

2023-08-16,,

https://mp.weixin.qq.com/s/shnnqoyf-t8i2j85e1osya

如果想直接在域名的根目录直接加载 swagger 比如访问:localhost:8001 就能访问,可以这样设置:

app.useswaggerui(c =>
{
c.swaggerendpoint("/swagger/v1/swagger.json", "apihelp v1");
c.routeprefix = "";//路径配置,设置为空,表示直接访问该文件,
//路径配置,设置为空,表示直接在根域名(localhost:8001)访问该文件,注意localhost:8001/swagger是访问不到的,
//这个时候去launchsettings.json中把"launchurl": "swagger/index.html"去掉, 然后直接访问localhost:8001/index.html即可

});

书接上文《从零开始搭建自己的前后端分离【 .net core2.0 api vue 2.0 】框架之三 || swagger的使用 3.1》,上文中只是简单的对如何使用swagger作了介绍,而且最后也提出了几个问题,这里再重温下那几个问题:

为何直接 f5 运行,凯发k8天生赢家一触即发首页还是无法加载?

接口虽有,但是却没有相应的文字说明?

项目开发中的实体类是如何在swagger中展示的?

对于接口是如何加权限验证的?

0、设置swagger页面为凯发k8天生赢家一触即发首页——开发环境

在上一回中我们提到,我们直接f5运行项目,出现了系统默认页,

虽然可以在输入/swagger后,顺利的访问swagger ui页,但是我们发现每次运行项目,都会默认访问api/values这个接口,我想要将启动页设为swagger(或者是任意一个页面),你就需要用到了

**设置文件launchsettings.json **了:

然后你再一次f5 运行,就会发现不一样了,其他的配置,以及以后部署中的设置,我们会在以后的文章中都有提到。

1、设置默认直接凯发k8天生赢家一触即发首页访问 —— 生产环境

上边的方法很正常,直接这么运行,就可以了,但是如果我们部署到服务器,就会发现,上边的那种默认启动凯发k8天生赢家一触即发首页无效了,还是需要我们每次手动在域名后边输入 /swagger ,麻烦!

别慌,swagger 给我们提供了这个扩展,我们可以指定一个空字符,作为 swagger 的地址,在configure中配置中间件:

 app.useswagger();
app.useswaggerui(c =>
{
c.swaggerendpoint($"/swagger/v1/swagger.json", $"blog.core v1");// 将swagger设置成凯发k8天生赢家一触即发首页
c.routeprefix = ""; //路径配置,设置为空,表示直接在根域名(localhost:8001)访问该文件,注意localhost:8001/swagger是访问不到的,去launchsettings.json把launchurl去掉
});

然后再把我们上边的项目文件 launchsettings.json 的 launchurl 给去掉就行了,这样我们无论是本地开发环境,还是生产环境,都可以默认凯发k8天生赢家一触即发首页加载了。

比如我的在线地址 :apk.neters.club/

2、为接口添加注释

接下来,我们就需要解决第二个问题,如何增加文字说明,就是传说中的注释,我们只需要在需要的api接口方法上,连点三次 / 即可:

添加好了注释,那我们接下来就需要把注释信息导入到swagger里,需要用到xml文档,右键web 项目名称=>属性=>生成,勾选“输出”下面的“xml文档文件”,系统会默认生成一个,当然老规矩,你也可以自己起一个名字:

这里我用的是相对路径,可以直接生成到 api 层的 bin文件夹下:

 

有了注释和文档,那接下来就是导入了,也是很简单,只需要一行即可:

 var basepath = appcontext.basedirectory;
var xmlpath = path.combine(basepath, "blog.core.xml");//这个就是刚刚配置的xml文件名
c.includexmlcomments(xmlpath);

运行查看,没问题!

3、忽略注释警告

这个时候,我们看看有没有错误,一看,咦~~~果然,虽然是警告,可以强迫症呀,一看还挺多

别慌!一看,哦!原来是swagger把一些 action 方法都通过xml文件配置了,如果你不想每一个方法都这么加注释,可以这么配置(对当前项目进行配置,可以忽略警告,记得在后边加上分号 ;1591):

这时候你可以看看,所有的警告都已经消失不见了。

4、给控制器也添加注释

刚刚可能你没太注意,我们上边只是给方法加了注释,但是控制器还没有加上,那怎么办呢,有一个复杂的方法,就是添加一个过滤器  c.documentfilter(); ,然后自己添加一个 .tags ,但是这个麻烦!不多说,官方已经考虑到了这个问题了,很简单:

首先我们在控制器上加上注释:

然后配置swagger的 xml 文档导入方法:

当当当,出来了:

5、对 model 也添加注释说明

接下来开始第三个问题:添加实体类说明注释

新建一个.net core 类库blog.core.model,注意是 .net core的类库,或者使用标准库也是可以的!(标准库可以在 netcore 和 framework 两个项目都可以跑)

 
新建一个love的实体类

    /// 
/// 这是爱
///

public class love
{
///
/// id
///

public int id { get; set; }
///
/// 姓名
///

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

public int age { get; set; }
}

 
这里现在有两个情况,或者说是两个操作方案:
 
1、当前 api 层直接引用了 blog.core.model 层;

这个时候,我们只需要配置仿照上边 api 层配置的xml文档那样,在 blog.core.model 层的 xml 输出到 api 层就行了:

2、api 层没有直接引用 model 层,而是通过级联的形式;

就比如我的 github 上的代码那样:

效果和上边是一样的,也算是引用 model 层了。

 

6、导入model.xml到swagger,然后api添加参数

配置xml文档

 public void configureservices(iservicecollection services)
{
services.addmvc().setcompatibilityversion(compatibilityversion.version_2_1); #region swagger
services.addswaggergen(c =>
{
c.swaggerdoc("v1", new info
{
version = "v0.1.0",
title = "blog.core api",
description = "框架说明文档",
termsofservice = "none",
contact = new swashbuckle.aspnetcore.swagger.contact { name = "blog.core", email = "blog.core@xxx.com", url = "https://www.jianshu.com/u/94102b59cc2a" }
}); //就是这里
var basepath = microsoft.dotnet.platformabstractions.applicationenvironment.applicationbasepath;
var basepath2 = appcontext.basedirectory;// 这种写法也是可以的
    
//就是这里
var xmlpath = path.combine(basepath, "blog.core.xml");//这个就是刚刚配置的xml文件名
c.includexmlcomments(xmlpath, true);//默认的第二个参数是false,这个是controller的注释,记得修改 var xmlmodelpath = path.combine(basepath, "blog.core.model.xml");//这个就是model层的xml文件名
c.includexmlcomments(xmlmodelpath); }); #endregion }

接口添加注释

     /// 
/// post
///

/// model实体类参数
[httppost]
public void post(love love)
{
}

dang dang dang,就出来了

 
 

7、去掉swagger警告提示

在model层中,我们建立了很多实体,如果你没有为每一个实体都添加注释的话,可能会出现这样的警告:

如果有的小伙伴,不想添加注释,而又不想看到这个强迫症的警告提示,那就可以这么做,

右键项目 属性 -》 errors and warnings 配置 1591:

8、隐藏某些接口

如果不想显示某些接口,直接在controller 上,或者action 上,增加特性

[apiexplorersettings(ignoreapi = true)]

9、自定义 swagger index 静态页模板

有时候我们为了在页面上增加一些小东西,比如说一个图片或者说,修改部分css样式,甚至更改 js 事件,那我们就必须修改 index.html 页面,很简单:

1、首先我们在 api 根目录下边创建一个 index.html 页面,








%(documenttitle)






%(headcontent)

































我们可以在里边简单的修改 css 样式,或者js 事件,但是注意,如果个人能力不是很高的话,建议不要修改。

2、然后我们修改中间件,替换掉 swagger 的默认凯发k8天生赢家一触即发首页

 app.useswaggerui(c =>
{
//根据版本名称倒序 遍历展示
var apiname = "blog.core";//这里你可以从appsettings.json中获取,比如我封装了一个类appsettings.cs,具体查看我的源代码
var version = "v1";
c.swaggerendpoint($"/swagger/{version}/swagger.json", $"{apiname} {version}"); // 将swagger凯发k8天生赢家一触即发首页,设置成我们自定义的页面,记得这个字符串的写法:凯发k8天生赢家一触即发的解决方案名.index.html
c.indexstream = () => gettype().gettypeinfo().assembly.getmanifestresourcestream("blog.core.index.html");//这里是配合miniprofiler进行性能监控的,《文章:完美基于aop的接口性能分析》,如果你不需要,可以暂时先注释掉,不影响大局。
c.routeprefix = ""; //路径配置,设置为空,表示直接在根域名(localhost:8001)访问该文件,注意localhost:8001/swagger是访问不到的,去launchsettings.json把launchurl去掉,如果你想换一个路径,直接写名字即可,比如直接写c.routeprefix = "doc";
});

完成,就是这么简单。

对于接口是如何加权限验证的?

让我们带着这些问题,继续浏览下一篇吧,swagger 3.3 jwt 权限,必看篇。

https://github.com/anjoy8/blog.core.git

https://gitee.com/laozhangisphi/blog.core

从壹开始前后端分离【 .net core2.0 vue2.0 】框架之四 || swagger的使用 3.2的相关教程结束。

网站地图