1.1 加入依赖
<!--swagger图形化接口-->
<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>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.8.7</version>
</dependency>1.2 在config包中写swagger配置类SwaggerConfig
swagger配置类的代码如下：（直接套用，但部分需要修改）
package com.ieslab.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
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(Environment environment){
// 设置要现实的swagger环境
Profiles profiles = Profiles.of("dev","test");
// 获取项目的环境,如果项目环境在profiles中则返回true
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) //配置 Swagger ApiInfo 基本信息
.groupName("jiangzeyu")
.enable(flag) //配置是否启动swagger
.select()
//RequestHandlerSelector配置要扫描接口的方式
//basePackage：指定要扫描的包
.apis(RequestHandlerSelectors.basePackage("com.ieslab.demo.controller"))
/*
* paths()：只扫描哪些类
* any()代表扫描全部
* none()代表都不扫描
* withClassAnnotation:扫描类上有某个注解的接口，比如说RestController就是扫描类上有@RestController的类生成接口
* withMethodAnnotation:扫描方法上有某个注解的接口，比如说GetMapping就是扫描方法上有@GetMapping的类生成接口
* ant(“/hello/*”)：扫描包含/hello/**请求的类生成接口
*/
.paths(PathSelectors.any())
.build(); //工厂模式
}
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A").enable(true);
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B").enable(true);
}
//配置 Swagger信息=apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("zhangsan","无","333@qq.com");
return new ApiInfo("Swagger API 文档", //文档标题
"这个是一个 Swagger 接口文档。", //文档描述
"v1.0", //文档版本
"没有网站", //队伍的网站地址
contact, //作者信息
"Apache 2.0", //许可证
"http://www.apache.org/licenses/LICENSE-2.0",//许可证Url
new ArrayList());
}
}
剖析：
在类上要加入两个注解：@Configuration和@EnableSwagger2；
然后开始写docket方法，返回Docket对象，入参是Environment environment，用来后续对application的环境进行判断，控制swagger是否启动：
// 设置要现实的swagger环境,dev代表application-dev.yaml
Profiles profiles = Profiles.of("dev","test");
// 获取项目的环境,如果项目环境在profiles中则返回true
boolean flag = environment.acceptsProfiles(profiles);
接着，返回配置的Docket对象：
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 配置 Swagger ApiInfo 基本信息,因此要创建apiInfo方法
.groupName("jiangzeyu")
.enable(flag) //配置是否启动swagger
.select()
//RequestHandlerSelector配置要扫描接口的方式
//basePackage：指定要扫描的包
.apis(RequestHandlerSelectors.basePackage("com.ieslab.demo.controller"))
/*
* paths()：只扫描哪些类,()里的参数有any()、none()、ant(“需要扫描的请求”)、withClassAnnotation、withMethodAnnotation,后面两个不常用，请自行百度
* any()代表扫描全部
* none()代表都不扫描
* withClassAnnotation:扫描类上有某个注解的接口，比如说RestController就是扫描类上有@RestController的类生成接口
* withMethodAnnotation:扫描方法上有某个注解的接口，比如说GetMapping就是扫描方法上有@GetMapping的类生成接口
* ant(“/hello/*”)：扫描包含/hello/**请求的类生成接口
*/
.paths(PathSelectors.any())
.build(); //工厂模式
}其中，apiInfo传入apiInfo方法返回的ApiInfo对象（需要自己写apiInfo方法），enable传入的参数可由项目的环境决定，apis(RequestHandlerSelectors.basePackage())传入的是需要扫描的包路径，paths()传入的是在包路径下扫描哪些类，groupName() 传入的是测试接口归属哪个人，如下图所示：
多个docket方法就可以代表不同人的测试接口：（注意方法名不要相同！）
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A").enable(true);
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B").enable(true);
}效果：
apiInfo()方法如下：套模板即可。
//配置 Swagger信息=apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("zhangsan","无","333@qq.com");
return new ApiInfo("Swagger API 文档", //文档标题
"这个是一个 Swagger 接口文档。", //文档描述
"v1.0", //文档版本
"没有网站", //队伍的网站地址
contact, //作者信息
"Apache 2.0", //许可证
"http://www.apache.org/licenses/LICENSE-2.0",//许可证Url
new ArrayList());
}1.3 创建实体类User
package com.ieslab.demo.emtity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("这是User的实体类") // 给实体类加文档注释
public class User {
@ApiModelProperty("主键id")
private Integer userId;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
剖析：只要实体类在Controller被使用，而控制类又被swagger扫描到，就会被展示出来，实体类的注解都是给文档加注释用的。
1.4 创建UserDao接口和UserDaoImpl实现类
UserDao：
package com.ieslab.demo.dao;
import com.ieslab.demo.emtity.User;
public interface UserDao {
// 添加用户
User addUser(Integer userId,String userName,String password);
}
UserDaoImpl：因为前端传来的是一个JSON对象，会使用@RequestBody将其封装为User对象，然后从这个User对象中拿各个属性。
package com.ieslab.demo.dao.impl;
import com.ieslab.demo.dao.UserDao;
import com.ieslab.demo.emtity.User;
import org.springframework.stereotype.Repository;
import java.util.HashMap;
import java.util.Map;
@Repository
public class UserDaoImpl implements UserDao {
private static Map<Integer,User> userMap = null;
static {
userMap = new HashMap<Integer, User>();
userMap.put(100,new User(100,"zhangsan","777"));
userMap.put(102,new User(102,"lisi","888"));
userMap.put(103,new User(103,"wangwu","999"));
userMap.put(104,new User(104,"zhaoliu","000"));
}
@Override
public User addUser(Integer userId,String userName,String password) {
User user = new User(userId,userName,password);
userMap.put(user.getUserId(),user);
return user;
}
}
1.5 创建Controller对象，接收请求
package com.ieslab.demo.controller;
import com.ieslab.demo.dao.UserDao;
import com.ieslab.demo.emtity.User;
import io.swagger.annotations.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@Slf4j
@RestController
public class MyController {
@Autowired // 相当于使用new UserDaoimpl()
private UserDao userDao;
@PostMapping(value = "/addUser")
@ApiOperation(value = "AddUser接口",httpMethod = "POST",notes = "这是AddUser接口的详细说明") // 给方法加注释
public User addUser(@RequestBody @ApiParam("用户") User userInput){ // 加入@RequestBody Spring自动将传过来的JSON类型的数据和我们的类匹配，说明输入是JSON格式的数据
User user = userDao.addUser(userInput.getUserId(), userInput.getUsername(), userInput.getPassword());
return user;
}
}
剖析：
重点在于Post方法不能接收基本类型的数据，需要把它们用JSON格式进行封装，然后@RequestBody会把JSON格式的数据转为对应的实体类。
注意！类上的是@RestController而不是@Controller，因为@Controller后类中的方法return的要转发的页面，而不会被以指定的格式写入Http response body中。
其他大部分注解都是加注释用的：
1.6 使用swagger进行测试
访问：http://localhost:8080/swagger-ui.html
然后选择自己的组，点击控制类：
点击要测试的接口（方法）：
点击try it out开始测试：
编辑要传入的JSON数据，编辑后执行：
测试成功：
![·[K8S：使用calico网络插件]：解决集群节点NotReady问题](https://img-blog.csdnimg.cn/974b41cf6b0d4f2eb233893423573705.png)
