简介
该项目主要利用Spring boot2.0 +Swagger2 方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。
- 源码地址
- GitHub：
- 联盟公众号：IT实战联盟
- 我们社区：
小工具一枚，欢迎使用和Star支持，如使用过程中碰到问题，可以提出Issue，我会尽力完善该Starter
版本基础
- Spring Boot：2.0.4
- Swagger2：2.7.0
操作步骤
第一步：下载SpringBoot2.0项目
- GitHub地址：
- 参考文档：
第二步：添加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@EnableSwagger2public 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", "zhenghhgz@163.com")) .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("/")@RestControllerpublic 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")@RestControllerpublic 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("zhenghhgz@163.com"); 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("jackma@163.com"); user.setUserStatus(1); return ResponseEntity.ok(user); }}复制代码 备注
- 使用Params和Param 实现了两种不同的数据传输方式
- 建议使用Spring的 ResponseEntity 类做统一的返回结果
- swagger 对 response code 的支持还算好，我们可以把可能出现的异常代码都一一罗列出来，方便对接的时候对异常的处理
第八步：启动运行
http://127.0.0.1:8081/api复制代码
备注
- 端口号已自己配置为准
如下图所示：