0
0

SpringBoot 整合Swagger2

一、Swagger简介

Swagger是一套开源工具和规范，用于设计、构建和文档化

RESTful Web

服务。它允许开发人员定义API的各个方面，并生成易于理解的API文档和交互式API探索界面。同时，Swagger还提供代码生成工具，可自动生成与API交互的客户端和服务器端代码，提高开发效率。

二、SpringBoot集成Swagger

使用Swagger

要求：

jdk 1.8 +

否则swagger2无法运行

步骤：

  1. 新建一个SpringBoot-web项目
  2. 添加Maven依赖<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>
  3. 编写HelloController，测试确保运行成功！@RestControllerpublicclassHelloController{@RequestMapping("/hello")publicStringhello(){return"hello swagger";}}
  4. 要使用Swagger，我们需要编写一个配置类SwaggerConfig来配置 Swaggerpackagecom.liming.config;importorg.springframework.context.annotation.Configuration;importorg.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;importorg.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;importspringfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@EnableSwagger2// 开启Swagger2的自动配置publicclassSwaggerConfigextendsWebMvcConfigurationSupport{/** * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html * @param registry void */@OverrideprotectedvoidaddResourceHandlers(ResourceHandlerRegistry registry){// 解决静态资源无法访问 registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");// 解决swagger无法访问 registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");// 解决swagger的js文件无法访问 registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}
  5. 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；在这里插入图片描述

三、配置Swagger

  1. Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。@Bean//配置docket以配置Swagger具体参数publicDocketdocket(){returnnewDocket(DocumentationType.SWAGGER_2);}
  2. 可以通过apiInfo()属性配置文档信息//配置文档信息privateApiInfoapiInfo(){returnnewApiInfoBuilder().title("Swagger标题")// 标题.description("学习演示如何配置Swagger")//描述.version("v1.0")// 版本.contact(newContact("黎明","https://blog.csdn.net/weixin_46370595?type=blog","[email protected]")).build();}
  3. Docket 实例关联上 apiInfo()@BeanpublicDocketdocket(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}
  4. 重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；在这里插入图片描述

四、配置扫描接口

  1. 构建Docket时通过select()方法配置怎么扫描接口。@BeanpublicDocketdocket(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.liming.controller")).build();}
  2. 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类在这里插入图片描述
  3. 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：> 1、> > basePackage(final String basePackage)> > // 根据包路径扫描接口> 2、> > any()> > // 扫描所有，项目中的所有接口都会被扫描到> 3、> > none()> > // 不扫描接口> > 4、// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求> > > withMethodAnnotation(final Class<? extends Annotation> annotation)> > > 5、// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口> > > withClassAnnotation(final Class<? extends Annotation> annotation)>
  4. 除此之外，我们还可以配置接口扫描过滤：@BeanpublicDocketdocket(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))// 配置如何通过path过滤,即这里只扫描请求以/user开头的接口.paths(PathSelectors.ant("/user/**")).build();}
  5. 这里的可选值还有> > any()> > // 任何请求都扫描> > > none()> > // 任何请求都不扫描> > > regex(final String pathRegex) > > // 通过正则表达式控制> > > ant(final String antPattern)> > // 通过ant()控制

SwaggerConfig基础配置全代码

packagecom.liming.config;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importorg.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;importorg.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;importspringfox.documentation.builders.ApiInfoBuilder;importspringfox.documentation.builders.PathSelectors;importspringfox.documentation.builders.RequestHandlerSelectors;importspringfox.documentation.service.ApiInfo;importspringfox.documentation.service.Contact;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;importspringfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@EnableSwagger2// 开启Swagger2的自动配置publicclassSwaggerConfigextendsWebMvcConfigurationSupport{@Bean//配置docket以配置Swagger具体参数publicDocketdocket(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.limjing.controller"))// 只扫描controller接口.paths(PathSelectors.any())// 配置如何通过path过滤,即这里扫描所有请求的接口.build();}//配置文档信息privateApiInfoapiInfo(){returnnewApiInfoBuilder().title("Swagger标题")// 标题.description("学习演示如何配置Swagger")//描述.version("v1.0")// 版本.contact(newContact("黎明","https://blog.csdn.net/weixin_46370595?type=blog","[email protected]")).build();}/**
     * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
     *
     * @param registry void
     */@OverrideprotectedvoidaddResourceHandlers(ResourceHandlerRegistry registry){// 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");// 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");// 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}

五、配置Swagger开关

  1. 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了@BeanpublicDocketdocket(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(false)//配置是否启用Swagger，如果是false，在浏览器将无法访问.select().apis(RequestHandlerSelectors.basePackage("nuc.ss.swagger.controller")).paths(PathSelectors.ant("/ss/**")).build();}在这里插入图片描述
  2. 如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？@BeanpublicDocketdocket(Environment environment){// 设置要显示swagger的环境Profiles of =Profiles.of("dev","test");// 判断当前是否处于该环境// 通过 enable() 接收此参数判断是否要显示boolean flag = environment.acceptsProfiles(of);returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(flag).select().apis(RequestHandlerSelectors.basePackage("com.liming.controller")).paths(PathSelectors.ant("/user/**")).build();}
  3. 可以在项目中增加配置文件> application.yml ->spring.profiles.active=dev> application-dev.yml ->端口：8081> application-pro.yml->端口：8082结果：pro正式环境会关闭swagger功能

六、配置API分组

  1. 如果没有配置分组，默认是default。通过groupName()方法即可配置分组：@BeanpublicDocketdocket(Environment environment){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("黎明")// 配置分组// 省略配置....}
  2. 重启项目查看分组在这里插入图片描述
  3. 如何配置多个分组？配置多个分组只需要配置多个docket即可：@BeanpublicDocketdocket1(){returnnewDocket(DocumentationType.SWAGGER_2).groupName("group1");}@BeanpublicDocketdocket2(){returnnewDocket(DocumentationType.SWAGGER_2).groupName("group2");}@BeanpublicDocketdocket3(){returnnewDocket(DocumentationType.SWAGGER_2).groupName("group3");}
  4. 重启项目查看即可在这里插入图片描述

七、实体配置

  1. 新建一个实体类//@Api("注释")@ApiModel("用户实体")publicclassUser{@ApiModelProperty("用户名")privateString username;@ApiModelProperty("密码")privateString password;publicStringgetUsername(){return username;}publicvoidsetUsername(String username){this.username = username;}publicStringgetPassword(){return password;}publicvoidsetPassword(String password){this.password = password;}}
  2. 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：@RestControllerpublicclassHelloController{// /error默认错误请求@GetMapping("/hello")publicStringhello(){return"hello";}//只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中@PostMapping("/user")publicUseruser(){returnnewUser();}}
  3. 重启查看测试image-20200731200413725

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的.

  • @ApiModel为类添加注释
  • @ApiModelProperty为类属性添加注释

【注意点】：在正式发布的时候，关闭Swagger！！！

常用注解

Swagger的所有注解定义在

io.swagger.annotations

包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：
Swagger注解简单说明@Api(tags = “xxxController说明”)作用在接口类上@ApiOperation(“xxx接口说明”)作用在接口方法上@ApiModel(“xxxPOJO说明”)作用在模型类上：如VO、BO@ApiModelProperty(value = “xxx属性说明”,hidden = true)作用在类方法和属性上，hidden设置为true可以隐藏该属性@ApiParam(“xxx参数说明”)作用在参数、方法和字段上，类似@ApiModelProperty@ApiImplicitParam()用于描述API接口的参数信息(常用的属性包括：

name：参数名

,

value：参数的描述信息

,

paramType：参数的类型，可以是path、query、body、header、form等

,

dataType：参数的数据类型

,

required：参数是否必需，布尔值，默认为false

,

defaultValue：参数的默认值

我们也可以给请求的接口配置一些注释

  1. 在HelloController控制类中的接口添加api接口注释@RestControllerpublicclassHelloController{......@ApiOperation("Hello控制接口")@GetMapping("/hello")publicStringhello2(@ApiParam("用户名")String username){return"hello"+ username;}@ApiOperation("get测试")@GetMapping("/get")publicUserhello2(@ApiParam("用户")User user){return user;}@GetMapping("/users/{id}")@ApiOperation(value ="获取用户详情")@ApiImplicitParam(name ="id", value ="用户ID", paramType ="path", dataType ="Long", required =true)publicUsergetUserById(@PathVariable("id")Long id){// 获取用户详情的业务逻辑}@GetMapping("/users")@ApiOperation(value ="获取用户列表")@ApiImplicitParams({@ApiImplicitParam(name ="page", value ="页码", paramType ="query", dataType ="int", defaultValue ="1"),@ApiImplicitParam(name ="size", value ="每页数量", paramType ="query", dataType ="int", defaultValue ="10")})publicList<User>getUsers(@RequestParam(defaultValue ="1")int page,@RequestParam(defaultValue ="10")int size){// 获取用户列表的业务逻辑}}image-20200731201755001
  2. 进行try it out测试image-20200731202958255测试结果image-20200731203034702

拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

1、默认的 访问 http://localhost:8080/swagger-ui.html

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

在这里插入图片描述

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!--swaggerconfig解决高版本那里要换成doc.html--><!-- 引入swagger-bootstrap-ui包 /doc.html--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.1</version></dependency>

image-20200731205550845

八.微服务使用Knife4j

官网地址:https://doc.xiaominfo.com/

在这里插入图片描述

第一步：创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包，代码如下：

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.3.0</version></dependency>

第二步：配置yml属性，代码如下：

knife4j:enable:true#表示启用Knife4j，允许API文档生成和展示openapi:#表示配置OpenAPI相关的信息title: Knife4j官方文档 #设置了API文档的标题description: "`我是测试`,**你知道吗**#设置了API文档的描述email: [email protected] #电子邮件地址concat: 黎明 #联系人的名称version: v1.0 
    license: Apache 2.0 #API使用的许可证为"Apache 2.0"license-url: https://stackoverflow.com/ #提供了许可证的URL链接terms-of-service-url: https://stackoverflow.com/ #提供了服务条款的URL链接group:#分组信息default:group-name: default #分组名称api-rule: package #按照包来进行API的分组api-rule-resources:#指定了API规则的资源信息- com.liming.controller

第三步:新建一个接口Controller类，如下：

@Api(tags ="首页模块")@RestControllerpublicclassIndexController{@ApiImplicitParam(name ="name",value ="姓名",required =true)@ApiOperation(value ="向客人问好")@GetMapping("/sayHi")publicResponseEntity<String>sayHi(@RequestParam(value ="name")String name){returnResponseEntity.ok("Hi:"+name);}}

万事俱备，启动Spring Boot项目，浏览器访问Knife4j的文档地址即可查看效果

http://ip:端口/doc.html
标签： spring boot 后端 java
本文转载自: https://blog.csdn.net/weixin_46370595/article/details/132226212
版权归原作者 小钟不想敲代码 所有， 如有侵权，请联系我们删除。
登录后发布评论

“SpringBoot 整合Swagger2”的评论:

还没有评论
关于作者
...
overfit同步小助手
文章同步
相关阅读

网络安全法-网络运行安全

使用selenium/drissionpage时如何阻止chrome自动跳转http到https

docker desktop 里部署的Open WebUI 管理员密码忘记了的处理方法

在ubuntu20.04中搭建onsite比赛运行环境

利用开源的低代码表单设计器FcDesigner高效管理和渲染复杂表单结构

Kafka学习笔记

【前端】浏览器输入url到页面呈现发生了什么？

文章导航