可以做网站的行业,计算机信息网络系统,新乡网站seo,网站备案org一、Swagger简介注意点#xff01; 在正式发布的时候要关闭swagger#xff08;出于安全考虑#xff0c;而且节省内存空间#xff09;之前开发的时候#xff0c;前端只用管理静态页面#xff0c; http请求到后端#xff0c; 模板引擎JSP#xff0c;故后端是主力如今是前… 一、Swagger简介 注意点 在正式发布的时候要关闭swagger出于安全考虑而且节省内存空间 之前开发的时候前端只用管理静态页面 http请求到后端 模板引擎JSP故后端是主力 如今是前后端分离时代 后端后端控制层服务层数据访问层 前端前端控制层视图层 伪造后端数据JSON格式便不再需要后端 方便了开发等到前后端都开发完成之后便不再使用伪造数据而是访问远程后端接口前后端如何交互 API文档前后端相对独立松耦合甚至前后端可以部署在不同的服务器上因为是调用接口所以在哪个服务器上无所谓 产生的问题 前后端继承联调前端人员和后端人员无法做到及时协商 ----一定要尽早沟通解决解决方案 指定计划提纲实时更新API降低集成风险 前后端分离之后后端提供接口需要实时更新最新的消息及改动Swagger诞生官方网站https://swagger.io/官方文档https://github.com/swagger-api/swagger-core/wiki/AnnotationsRestFul Api文档在线自动生成工具 》Api文档与API定义同步更新直接运行可以在线测试API接口支持多种语言在项目使用Swagger需要springbox swagger2 ui需要上面的两个组件导入上面的两个坐标二、spring boot集成Swagger 第一步肯定是创建一个springboot项目第二步导入maven坐标万古不变的两步2.1 maven坐标 如果运行程序的时候出现错误或许可以将下面swagger-ui依赖和swagger2依赖的版本降低一些比如说降低到2.7.0 dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version/dependencydependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version/dependency
!-- web环境--dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactIdversion2.3.7.RELEASE/version/dependency如果适用2.7.0还会有错误建议降低springboot版本号到2.5.0 parentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion2.5.0/versionrelativePath/ !-- lookup parent from repository --/parent2.2 配置类Springboot集成swagger-ui.html访问不到404,那就降低我们刚刚两个左边的版本比如改成2.7.0两个依赖都要改如果在启动时出现了其他的方法也可以尝试将依赖的版本降低一些下面的这段代码是使用的默认的swagger配置Configuration //加入到容器里面
EnableSwagger2 //开启Swagger
public class SwaggerConfig {}2.3 启动并访问Swagger UI下面是效果图2.4 配置Swagger Swagger的bean实例Docket2.4.1 Swagger的bean实例DocketConfiguration //加入到容器里面
EnableSwagger2 //开启Swagger
public class SwaggerConfig {// 配置了Swagger的Docket实例Beanpublic Docket docket() {return new Docket(DocumentationType.SWAGGER_2);}
}2.4.1.1源码解析DocumentationType.SWAGGER_2含义 这个地方为什么传一个他呀我们看一下Docket构造器发现传入DocumentationType类型的参数我们查看一下DocumentationType类 我们再看一下这些字段很明显我们是2.0版本故传入DocumentationType.SWAGGER_2另外插一句话在我们还没有配置之前我们可以先点进这个Docket类中看一下有一个默认的分组现在我们在swagger-ui页面上观看一下具体是对应的哪一部分的信息 很明显是页面右上角的位置2.4.1.2 源码解析Swagger 配置信息 Docket.ApiInfo 在Docket类中找到下面这个构造方法并且可以查看一下ApiInfo.DEFAULT这个就是默认的下面我们就来看一下这个的源码在ApiInfo中我们成功找到这个字段将这个类往下翻翻还会发现一个静态代码块 我们发现静态代码块中的信息和swagger页面的信息是一个样子的说明这个就是默认的配置在类编译的时候就会加载DEFAULT就是在这个地方被赋值的 static {DEFAULT new ApiInfo(Api Documentation, Api Documentation, 1.0, urn:tos, DEFAULT_CONTACT, Apache 2.0, http://www.apache.org/licenses/LICENSE-2.0, new ArrayList());}上面的这些信息对下的就是swagger-ui页面的下图信息2.4.1.3 源码解析ApiInfo中的Contact参数我们在源码中发现其中DEFAULT_CONTACT是作者信息如下图所示发现都是空的2.4.2 如何替换掉默认ApiInfo下面我们将这个配置改一下如下代码所示Configuration //加入到容器里面
EnableSwagger2 //开启Swagger
public class SwaggerConfig {// 配置了Swagger的Docket实例Beanpublic Docket docket() {
// Docket有很多的配置我们可以先配置一个apiInfo()
// apiInfo()里面需要传入一个ApiInfo的参数那我们就在下面定义一个return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}// 配置Swagger信息 apiInfoprivate ApiInfo apiInfo(){
// 下面的这套配置就把原来的static代码块覆盖掉
// 作者信息通过查看源码得知Contact contact new Contact(张靖奇, https://blog.kuangstudy.com/, 1149345976qq.com);return new ApiInfo(张靖奇的API文档,练习,v1.0,https://blog.kuangstudy.com/,contact,Apache 2.0,http://www.apache.org/licenses/LICENSE-2.0,new ArrayList());}
}之前的效果图如今的效果图 假如说出不来下面的效果图仍然是上面的效果图给浏览器清理缓存再刷新即可 备注这个框框圈出来的东西至于文档名和描述信息有用其他的没有用2.4.3 Swagger配置扫描接口 Docket.select我们再select()之后继续加点我们发现只能再加上apispaths2.4.3.1 扫描指定的包 指定扫描com.example.controller包 Beanpublic Docket docket() {
// Docket有很多的配置我们可以先配置一个apiInfo()
// apiInfo()里面需要传入一个ApiInfo的参数那我们就在下面定义一个return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// select()参数里面需要传入一个Docket可以返回一个ApiSelectorBuilder.select()
// RequestHandlerSelectors,配置要扫描接口的方式
// basePackage(com.example) 指定扫描这个包.apis(RequestHandlerSelectors.basePackage(com.example.controller)).build();}2.4.3.2 扫描全部的包.apis(RequestHandlerSelectors.any())2.4.3.3 都不扫描 .apis(RequestHandlerSelectors.none())2.4.3.4 扫描类上的注解 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))2.4.3.5 扫描方法上的注解 .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))2.4.3.6 过滤路径 ant() 过滤路径的 表示在com.example.controller包下的路径为/kuang开头的所有请求.apis(RequestHandlerSelectors.basePackage(com.example.controller))
.paths(PathSelectors.ant(/kuang/**)) any()全部都过滤 none()全部都不过滤 regex()根据正则表达式过滤 2.4.4 配置是否启动Swagger查看Docket源码发现有一个enabed 默认为true表示启动Swagger 如果为false则Swagger不能在浏览器中访问我们也可以把这个值改成false注意 这个点的时候一定不要在build()后面点从select到build是一套的此时重启之后访问不到页面2.4.4.1 希望Swagger在生产环境中使用但发布时不适用判断是不是生产环境 flagfalse注入enable(flag)多配置是怎么来的怎么确定是生产环境还是发布环境acceptsProfiles(Profiles profiles) 监听,返回boolean其中Profiles是org.springframework.core.envgetDefaultProfiles() 获得默认的文件名返回String[]getActiveProfiles() 获得激活的文件名返回String[]如下代码所示我们配置的是当在devtest这两个版本下才能进入到swagger重启刷新swagger-ui界面他是直接访问不到的 Beanpublic Docket docket(Environment environment) {
// 获取项目的环境
// 这个地方是可变长参数可以写好几个Profiles profiles Profiles.of(dev,test);
// 如果是dev、test,这个地方的返回值就是trueboolean flag environment.acceptsProfiles(profiles);// Docket有很多的配置我们可以先配置一个apiInfo()
// apiInfo()里面需要传入一个ApiInfo的参数那我们就在下面定义一个return new Docket(DocumentationType.SWAGGER_2).enable(flag).apiInfo(apiInfo())
// select()参数里面需要传入一个Docket可以返回一个ApiSelectorBuilder.select().apis(RequestHandlerSelectors.basePackage(com.example.controller)).build();}此时我们修改一下application.yaml文件以及新增两个配置文件application.yaml#激活环境
spring:profiles:active: devapplication-dev.yamlserver:port: 8081application-pro.yamlserver:port: 8082修改及添加之后再次访问页面这次如果我们用8080端口是访问不到的因为我们在application中配置的是dev环境此时会直接向application-dev文件寻找成为8081端口2.4.5 配置Api文档的分组2.4.5.1 配置多个组 配置多个Docket然后点就行2.5 实体类配置只要我们的接口中的返回值存在实体类就会被扫描到Swagger(前提是Swagger会扫描到所在的包一定看好范围)RestController
RequestMapping(/test)
Api(value 测试一下)
public class TestController {GetMapping(/userinfo)ApiOperation(获取用户列表信息)public User getUserInfo(){User user new User();return user;}
}
public class User {public String user;public String password;
}效果如下图所示但是上边的都是英文一般人会看不懂但是我们可以加一些中文备注这些中文备注就需要用到下面的注解2.5.1 ApiModel 与ApiProperty(31条消息) ApiModel注解与ApiModelProperty注解_我爱布朗熊的博客-CSDN博客2.5.2 ApiOperation这个注解的作用就是给接口加了一个中文注释而已 GetMapping(/userinfo)ApiOperation(获取用户列表信息)public User getUserInfo(){User user new User(aaa,aaaaa);return user;}2.5.3 ApiParam GetMapping(/hello2)public String hello2(ApiParam(用户名) String username){return hello;}
