SpringBoot 集成Swagger

文章目录

1. swagger简介2. 新建一个基于web的spring boot项目3. 导入swagger依赖4. 自定义swagger-ui5. 配置扫描接口6. 配置swagger开关7. 配置API分组8. 实体类配置9. 常用注解10. 小结

1. swagger简介

前后端分离时代： 前端 -> 前端控制层，前端视图层 后端 -> 后端控制层，服务处，数据接入层 前后端通过API进行交互，可以使得程序独立且松耦合

swagger是什么？

swagger是一款让你更好的书写API文档的规范且完整的框架，提供了描述生产，消费和可视化的RESTful 风格编程，是由庞大的工具集合支撑的形式化规范，这个集合涵盖了从终端用户接口，底层代码到商业的API管理层面！

为什么要用swagger

swagger为前端和后端程序员提供了更为规范的API文档，减少在开发过程的各自产生的分歧！

使用swagger有什么好处？ 世界上最流行的API框架RESTful API文档在线自动生成器API文档和API定义同步更新直接运行，可以在线测试API支持多种语言，Java，C#，PHP等

2. 新建一个基于web的spring boot项目

测试最基本的环境：

编写controller

@RestController @RequestMapping("hello") public class HelloController { @RequestMapping("sayHello") public String sayHello(){ return "Hello Swagger"; } }

访问：http://localhost:8080/hello/sayHello 环境搭建完成！

3. 导入swagger依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>

访问：http://localhost:8080/swagger-ui.html

4. 自定义swagger-ui

@Configuration @EnableSwagger2 public class SwaggerConfig { //配置swagger的docket实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo()); } private ApiInfo getApiInfo(){ Contact contact = new Contact("liuzeyu12a", "https://me.csdn.net/blog/JAYU_37", "515801535@qq.com"); //没有set方法，所以只能通过构造器 return new ApiInfo("liuzeyu12a`Blog", "即使再小的帆也能远航", "1.0", "https://me.csdn.net/blog/JAYU_37", contact, "Apache 2.0", "http://apche.org/licenses/LISCENSE-2.0", new ArrayList<>()); } }

5. 配置扫描接口

WithMethodAnnotation(GetMapping.class)：表示只扫描方法上加了GetMapping的get请求 WithClassAnnotation(Controller.class)：表示只扫描类上加上了@Controller的接口

除此之外还可以配置接口扫描过滤 实例：

//配置swagger的docket实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2). apiInfo(getApiInfo()). select(). //select配置扫描的接口 apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")). paths(PathSelectors.ant("/haha/**")). //扫描controller包下haha包下的接口 build(); }

接口的扫描位置在com.liuzeyu.controller包下的/haha下的任意接口！ 此时写了一个控制类： swagger界面：

6. 配置swagger开关

如果有一个需求，让swagger在生产环境下使用！

准备多生产环境 swagger配置：

//配置swagger的docket实例 @Bean public Docket docket(Environment environment){ Profiles profiles = Profiles.of("dev","test"); boolean flag = environment.acceptsProfiles(profiles); System.out.println(flag); return new Docket(DocumentationType.SWAGGER_2). apiInfo(getApiInfo()). enable(flag). select(). //select配置扫描的接口 apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")). paths(PathSelectors.ant("/haha/**")). //扫描controller包下haha包下的接口 build(); }

生产环境下可以正常使用swagger 如果注释掉# spring.profiles.active=dev

则关闭swagger

7. 配置API分组

一个分组对应这个一个Docket实例。所有如果需要多个分组，我们应当在容器中注入多个Docket实例。

//配置swagger的docket实例 //分组:liuzeyu @Bean public Docket docket(Environment environment){ Profiles profiles = Profiles.of("dev","test"); boolean flag = environment.acceptsProfiles(profiles); System.out.println(flag); return new Docket(DocumentationType.SWAGGER_2). apiInfo(getApiInfo()). enable(flag). groupName("liuzeyu"). select(). //select配置扫描的接口 apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")). paths(PathSelectors.ant("/haha/**")). //扫描controller包下haha包下的接口 build(); } @Bean public Docket docket_A(){ return new Docket(DocumentationType.SWAGGER_2).groupName("A"); } @Bean public Docket docket_B(){ return new Docket(DocumentationType.SWAGGER_2).groupName("B"); }

实际开发中，不同的分组应当对应着不同的开发人员，这样大项目的接口开发分工就会更加明确！

8. 实体类配置

准备实体类： @ApiModel("用户实体类") public class User { @ApiModelProperty("用户名") public String username; @ApiModelProperty("用户密码") public String password; } 提供接口，返回值必须是实体类类型！ @PostMapping("/user") public User getUser(){ return new User(); } 启动swagger

9. 常用注解

运用在实体类上的注解有 @ApiModel :为实体类添加注释 @ApiModelProperty：为实体类属性添加注释 在io.swagger.annotations下，还有一些常用的注解：

swagger注解简单说明@Api(tag=“xxxx模块说明”)作用在类上@ApiOperation(“xxx接口说明”)作用在接口方法上@ApiParam(“xxx”)作用在j接口方法的字段上

主要目的就是为了生成友好的接口文档，让人跟容易阅读！

10. 小结

我们可以通过swagger给一些比较难理解的属性或接口增加注释信息，便于理解！接口文档实时更新可以在线测试！

参考：https://www.bilibili.com/video/BV1PE411i7CV?p=50