springboot2.x集成Swagger3

目的&＃xff1a;

在写这篇记录时&＃xff0c;swagger的最新版本到了3.0.0了&＃xff0c;在进行集成时&＃xff0c;没注意&＃xff0c;还按照2.0的集成&＃xff0c;走了一些弯路&＃xff0c;这里特记录下。

环境&＃xff1a;

一个已经搭建好的干净的springboot框架&＃xff0c;这个框架中我集成了mybatis.

什么是swagger&＃xff1f;

　Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。

    一个规范和完整的框架&＃xff0c;用于生成、描述、调用和可视化RESTful风格的Web服务&＃xff0c;加上swagger-ui&＃xff0c;可以有很好的呈现。

　当我们在后台的接口修改了后&＃xff0c;swagger可以实现自动的更新&＃xff0c;而不需要人为的维护这个接口进行测试。

 说的再简单点&＃xff0c;传统的我们开发好接口后&＃xff0c;都会通过单元测试或者如PostMan之类的测试工具进行接口的测试&＃xff0c;在接口少的时候这个还行&＃xff0c;可是现在大家都倡导前后端分离式的开发

导致后端全是接口&＃xff0c;随着业务的复杂&＃xff0c;一个项目路的 接口不要太多&＃xff0c;每个接口我们都要去写文档&＃xff0c;而且在过程中随着业务的编写接口还会不停的更新&＃xff0c;这样我们的测试工具就显得力不从心了&＃xff0c;而且大家也知道&＃xff0c;很多公司的文档都是后补的&＃xff0c;各种各样的原因导致可能文档中的接口与实际的接口差别还挺大。。。。。

那么这个时候&＃xff0c;我们通过swagger的引入&＃xff0c;在写接口的同时&＃xff0c;通过注解的方式在接口上写明接口的作用&＃xff0c;参数介绍等&＃xff0c;那么会在线生成一个接口 文档&＃xff0c;而且还可以直接进行测试&＃xff0c;还是随着实际的接口变动实时更新的&＃xff0c;这个是不是挺美的。这就是swagger

但是swagger是侵入式的&＃xff0c;说白了&＃xff0c;你要用它&＃xff0c;就得在每个对应的接口的地方都要写点注解&＃xff0c;虽然少&＃xff0c;但还是有&＃xff0c;这就侵入了我们现有的代码&＃xff0c;这点目前看来不是很友好。

springBoot集成swagger

第一步&＃xff1a;引入maven依赖&＃xff0c;在你项目的pom文件中&＃xff0c;引入下面依赖&＃xff1a;

io.springfoxspringfox-boot-starter3.0.0

第二步&＃xff1a;添加配置&＃xff0c;我再启动类的同级目录下添加swagger的配置类&＃xff0c;

package com.nj.appserver;import io.swagger.annotations.ApiOperation;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;/*** Swagger3配置类*/
&＃64;Configuration
public class Swagger3Config {&＃64;Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Swagger3接口文档").description("更多请咨询服务开发者XXX").contact(new Contact("作者", "作者地址", "作者邮箱")).version("1.0").termsOfServiceUrl("aaa").build();}
}


第三步&＃xff1a;在Application启动应用类上面加入&＃64;EnableOpenApi注解

package com.nj.appserver;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;&＃64;EnableOpenApi
&＃64;SpringBootApplication
public class AppServerApplication {public static void main(String[] args) {SpringApplication.run(AppServerApplication.class, args);}}


第四步&＃xff1a;在业务接口中添加swagger注解

package com.nj.appserver.controller;import com.github.pagehelper.PageHelper;
import com.github.pagehelper.PageInfo;import com.nj.appserver.pojo.SysUser;
import com.nj.appserver.service.SysUserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;import java.util.List;
&＃64;Api(value &＃61; "用户管理接口",tags &＃61; "用户信息接口类")
&＃64;RestController
&＃64;RequestMapping("sysUser")
public class SysUserController {&＃64;Autowiredprivate SysUserService sysUserService;/*** 查询* &＃64;return*/&＃64;ApiOperation("查询用户列表")&＃64;GetMapping("/findUserList")public List selectUserList(){List userList &＃61; sysUserService.selectUserList();return userList;}/*** 分页查询* &＃64;param pageNum 当前页数* &＃64;param pageSize 每页的记录条数* &＃64;return*/&＃64;ApiOperation("分页查询用户列表")&＃64;GetMapping("/findUserListByPage")public PageInfo getUserBySearch(&＃64;RequestParam("pageNum") int pageNum,&＃64;RequestParam("pageSize") int pageSize) {// TODO Auto-generated method stubPageHelper.startPage(pageNum,pageSize);List list&＃61; sysUserService.selectUserList();PageInfo pageInfo &＃61; new PageInfo(list);pageInfo.toString();return pageInfo;}
}


第五步&＃xff1a;启动项目&＃xff0c;访问swaggerui界面&＃xff0c;注意&＃xff0c;swagger3更新后&＃xff0c;可访问ui界面路径与之前不同&＃xff1b;

http://localhost:【端口号】/[content-path]/swagger-ui/index.html

 附&＃xff1a;常用的swagger注解

&＃64;Api&＃xff1a;用在请求的类上&＃xff0c;表示对类的说明tags&＃61;"说明该类的作用&＃xff0c;可以在UI界面上看到的注解"value&＃61;"该参数没什么意义&＃xff0c;在UI界面上也看到&＃xff0c;所以不需要配置"&＃64;ApiOperation&＃xff1a;用在请求的方法上&＃xff0c;说明方法的用途、作用value&＃61;"说明方法的用途、作用"notes&＃61;"方法的备注说明"&＃64;ApiImplicitParams&＃xff1a;用在请求的方法上&＃xff0c;表示一组参数说明&＃64;ApiImplicitParam&＃xff1a;用在&＃64;ApiImplicitParams注解中&＃xff0c;指定一个请求参数的各个方面name&＃xff1a;参数名value&＃xff1a;参数的汉字说明、解释required&＃xff1a;参数是否必须传paramType&＃xff1a;参数放在哪个地方· header --> 请求参数的获取&＃xff1a;&＃64;RequestHeader· query --> 请求参数的获取&＃xff1a;&＃64;RequestParam· path&＃xff08;用于restful接口&＃xff09;--> 请求参数的获取&＃xff1a;&＃64;PathVariable· body&＃xff08;不常用&＃xff09;· form&＃xff08;不常用&＃xff09; dataType&＃xff1a;参数类型&＃xff0c;默认String&＃xff0c;其它值dataType&＃61;"Integer" defaultValue&＃xff1a;参数的默认值&＃64;ApiResponses&＃xff1a;用在请求的方法上&＃xff0c;表示一组响应&＃64;ApiResponse&＃xff1a;用在&＃64;ApiResponses中&＃xff0c;一般用于表达一个错误的响应信息code&＃xff1a;数字&＃xff0c;例如400message&＃xff1a;信息&＃xff0c;例如"请求参数没填好"response&＃xff1a;抛出异常的类&＃64;ApiModel&＃xff1a;用于响应类上&＃xff0c;表示一个返回响应数据的信息&＃xff08;这种一般用在post创建的时候&＃xff0c;使用&＃64;RequestBody这样的场景&＃xff0c;请求参数无法使用&＃64;ApiImplicitParam注解进行描述的时候&＃xff09;&＃64;ApiModelProperty&＃xff1a;用在属性上&＃xff0c;描述响应类的属性