简介
该项目主要利用Spring boot2.0 +Swagger2 方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。
- 源码地址
- GitHub：https://github.com/yundianzixun/spring-boot-starter-swagger2
- 联盟公众号：IT实战联盟
- 我们社区：https://100boot.cn
小工具一枚，欢迎使用和Star支持，如使用过程中碰到问题，可以提出Issue，我会尽力完善该Starter
版本基础
- Spring Boot：2.0.4
- Swagger2：2.7.0
操作步骤
第一步：下载SpringBoot2.0项目
- GitHub地址：https://github.com/yundianzixun/spring-boot-starter
- 参考文档：https://www.jianshu.com/p/7dc2240f010e
第二步：添加maven依赖
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
org.apache.tomcat.embed
tomcat-embed-jasper
org.springframework.boot
spring-boot-starter-tomcat
provided
org.springframework.boot
spring-boot-starter-web
第三步：application.properties 增加swagger配置
#开启swagger服务
swagger.enable=true
第四步：使用注解配置Swagger
@Configuration
@EnableSwagger2
public class Swagger2Config {
public static final String BASE_PACKAGE = "com.itunion";
@Value("${swagger.enable}")
private boolean enableSwagger;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 生产环境的时候关闭 swagger 比较安全
.enable(enableSwagger) //将Timestamp类型全部转为Long类型
.directModelSubstitute(Timestamp.class, Long.class) //将Date类型全部转为Long类型
.directModelSubstitute(Date.class, Long.class)
.select() // 扫描接口的包路径，不要忘记改成自己的
.apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() { return new ApiInfoBuilder()
.title("Swagger RESTful APIs")
.description("Swagger API 服务")
.termsOfServiceUrl("http://swagger.io/")
.contact(new Contact("Swagger", "127.0.0.1", "[email protected]"))
.version("1.0")
.build();
}
}
备注
- 正常项目上线后应该是关闭掉 swagger 的，所以这边增加了一个配置 enableSwagger
- 可以使用 directModelSubstitute 做一些期望的类型转换
第五步：创建用户实体类UserInfo
public class UserInfo {
@ApiModelProperty("编号")
private Long id;
@ApiModelProperty("用户名")
private String userName;
@ApiModelProperty("姓")
private String firstName;
@ApiModelProperty("名")
private String lastName;
@ApiModelProperty("邮箱")
private String email;
@ApiModelProperty(hidden = true)// 密码不传输
@JsonIgnore
private String password;
@ApiModelProperty("状态")
private Integer userStatus;
/**此处省略get、set **/
}
第六步：编写一个首页的Controller
@Api(value = "首页", description = "首页")
@RequestMapping("/")
@RestController
public class IndexController {
@ApiOperation(value = "Hello Spring Boot", notes = "Hello Spring Boot")
@RequestMapping(value = "/", method = RequestMethod.GET)
public String index() {
return "Hello Spring Boot";
}
@ApiOperation(value = "API 页面", notes = "接口列表")
@RequestMapping(value = "/api", method = RequestMethod.GET)
public void api(HttpServletResponse response) throws IOException {
response.sendRedirect("swagger-ui.html");
}
}
- 为了方便访问swagger ui 页面，我们做了一个重定向 api 更方便些
第七步：编写一个登陆的Controller
@Api(value = "用户", description = "用户")
@RequestMapping("/userInfo")
@RestController
public class UserInfoController {
@ApiOperation(value = "登录接口-多值传值方式", notes = "输入用户名和密码登录")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK", response = UserInfo.class, responseContainer = "userInfo"),
@ApiResponse(code = 405, message = "账号名或密码错误")
})
@ApiImplicitParam(name = "map", value = "{\"userName\":\"JackMa\",\"passWord\":\"123\"}")
@RequestMapping(value = "loginForMap", method = RequestMethod.POST, produces= MediaType.APPLICATION_JSON_UTF8_VALUE)
ResponseEntity loginForMap(@RequestBody Map map) {
if (!map.get("userName").equalsIgnoreCase("JackMa") || !map.get("passWord").equalsIgnoreCase("123")) {
return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED).build();
}
UserInfo user = new UserInfo();
user.setId(1L);
user.setUserName("JackMa");
user.setFirstName("马");
user.setLastName("云");
user.setEmail("[email protected]");
user.setUserStatus(1);
return ResponseEntity.ok(user);
}
@ApiOperation(value = "登录接口-多值传输方式", notes = "输入用户名和密码登录")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK", response = UserInfo.class, responseContainer = "userInfo"),
@ApiResponse(code = 405, message = "账号名或密码错误")
})
@ApiImplicitParams({
@ApiImplicitParam(name = "userName",value = "用户名", required = true, dataType = "string", paramType = "query"),
@ApiImplicitParam(name = "passWord",value = "密码", required = true, dataType = "string",paramType = "query"),
})
@RequestMapping(value = "loginForParams", method = RequestMethod.POST, produces= MediaType.APPLICATION_JSON_UTF8_VALUE)
ResponseEntity loginForMap(@RequestParam String userName, @RequestParam String passWord) {
if (!userName.equalsIgnoreCase("JackMa") || !passWord.equalsIgnoreCase("123")) {
return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED).build();
}
UserInfo user = new UserInfo();
user.setId(1L);
user.setUserName("JackMa");
user.setFirstName("马");
user.setLastName("云");
user.setEmail("[email protected]");
user.setUserStatus(1);
return ResponseEntity.ok(user);
}
}
备注
- 使用Params和Param 实现了两种不同的数据传输方式
- 建议使用Spring的 ResponseEntity 类做统一的返回结果
- swagger 对 response code 的支持还算好，我们可以把可能出现的异常代码都一一罗列出来，方便对接的时候对异常的处理
第八步：启动运行
http://127.0.0.1:8081/api
备注
- 端口号已自己配置为准
如下图所示：
swagger2.jpg
第九步：执行
输入.jpg
输出.jpg
贡献者
- IT实战联盟-Line
- IT实战联盟-咖啡
更多精彩内容可以关注“IT实战联盟”公众号哦~~~
image