springboot整合swagger2
1,概念
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
2,使用swagger优势
支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
3,接下来开始整合，使用springboot项目，有web框架支持即可
4,需要的依赖
使用2.9.2版本稍微稳定一些
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
5,新建一个config包，再新建一个SwaggerTest类
package com.example.demo.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration //点进源码可以发现该注解等价于Component
//开启swagger2
@EnableSwagger2
public class SwaggerTest {
}
6，运行项目，并在浏览器中输入http://localhost:8080/swagger-ui.html,出现以下界面，项目就初始化好了
7,配置属于自己的文档
由于在Docket类下的所有参数都是使用默认的参数（点击Docket源码即可知），正如上图界面中的参数都是默认的，因此可以重写类里面的方法以及修改方法中的参数
package com.example.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration //点进源码可以发现该注解等价于Component
//开启swagger2
@EnableSwagger2
public class SwaggerTest {
@Bean
public Docket docket(){
* DocumentationType.SWAGGER_2：点进Docket可以发现构造方法中需要一个参数，
* 在点进这个参数类DocumentationType就能发现具体的参数了
*/
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
//是否启动swagger，如果参数为false，那么浏览器则禁止访问swagger
//.enable(true)
.groupName("郑辉盛")
//.select ** .build为一套模板
.select()
//RequestHandlerSelectors:配置要扫描接口的方式，
// basePackage：可以指定要扫描的包
// any:扫描全部
//none：不扫描
//withMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.example.demo"))
//过滤什么路径
//.paths(PathSelectors.ant("/demo/**"))
.build();
}
//配置swagger信息apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("郑辉盛","","[email protected]");
return new ApiInfo(
"郑辉盛的swagger文档", //标题
"即使再小的帆也能远航", //描述
"1.0", //版本
"https://blog.csdn.net/zhenghuishengq",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
8，再次运行，可以得到自己所设置的参数的界面了，右上角出现的那个为组名，就是.groupName(“郑辉盛”)所设置的
9，如果想多个人同时开发，就可以设置多个组名，因此需要多个Docket对象，可以在上诉代码中加入
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("a");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("b");
}
@Bean
public Docket docket4(){
return new Docket(DocumentationType.SWAGGER_2).groupName("c");
}
@Bean
public Docket docket5(){
return new Docket(DocumentationType.SWAGGER_2).groupName("d");
}
10,再次测试，可以发现多出了几个模块
11，以自己的模块进行测试，新建一个pojo包，并再建一个实体类User
package com.example.demo.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//给生成的文档注释
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String name;
@ApiModelProperty("密码")
public String password;
public User(String name, String password) {
this.name = name;
this.password = password;
}
public User(){
}
}
12,新建一个controller包，新建一个HelloController类
package com.example.demo.controller;
import com.example.demo.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@Api("HelloController控制类")
@RestController //没有界面，返回一个字符串
public class HelloController {
@GetMapping(value = "/hello")
public String hello(){
return "hello";
}
@GetMapping(value = "/user")
public User getUser(){
return new User("郑辉盛","123456");
}
@ApiOperation("hello控制类")
@PostMapping("/hello2")
public String hello2(@ApiParam("用户名") String userName){
return "hello" + userName;
}
@ApiOperation("Post测试类")
@PostMapping("/hello3")
public User hello3(@ApiParam("用户名") User user){
return user;
}
}
13,直接运行,
在Models中可以发现实体类，以及生成的文档注释
再次点开hello-controller
14，接下来到了紧张有刺激的开发人员测试环节
点开/hello3这个接口，并点击try it out，最后执行
最终出现以下界面，说明接口测试成功，没问题！
15，总结
可以通过swagger给一些比较难理解的属性或者接口，增加注释信息
接口文档实时更新
可以在线测试