Swagger 又称丝袜哥,号称可以让程序员边写代码边生产接口文档。
在 pom.xml
中添加 Swagger 2 所需依赖:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } }
Swagger 通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
@Api @ApiOperation @ApiParam @ApiModel @ApiProperty @ApiResponse @ApiResponses @ApiIgnore @ApiImplicitParam @ApiImplicitParams
以上这些就是最常用的几个注解了。
具体其他的注解,查看: https://github.com/swagger-ap...
更多请参考 Swagger 注解文档
@Api(value = "用户管理", description = "用户信息的「增、删、查、改」操作") @RestController @RequestMapping(path = "/sample/users") public class UserController { private static Map<Long, UserModel> users = Collections.synchronizedMap(new HashMap<>()); @ApiOperation(value = "用户列表") @GetMapping(path = "/") public List<UserModel> getUserList() { return new ArrayList<>(users.values()); } @ApiOperation(value = "创建用户", notes = "根据 User 对象创建用户") @ApiImplicitParam(name = "user", value = "用户详细实体", required = true, dataTypeClass = UserModel.class) @PostMapping(path = "/") public UserModel createUser(@RequestBody UserModel user) { users.put(user.getId(), user); return user; } @ApiOperation(value = "用户详细信息", notes = "根据 ID 获取用户详细信息") @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Long") @GetMapping(path = "/{id}") public UserModel getUser(@PathVariable Long id) { return users.get(id); } @ApiOperation(value = "更新用户详细信息", notes = "根据 ID 指定更新对象, 并根据 User 信息来更新用户详细信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataTypeClass = Long.class), @ApiImplicitParam(name = "user", value = "用户详细实体", required = true, dataTypeClass = UserModel.class) }) @PutMapping(path = "/{id}") public UserModel updateUser(@PathVariable Long id, @RequestBody UserModel user) { UserModel updateUser = users.get(id); updateUser.setName(user.getName()); updateUser.setAge(user.getAge()); updateUser.setEmail(user.getEmail()); users.put(id, updateUser); return updateUser; } @ApiOperation(value = "删除用户", notes = "根据 ID 指定删除对象") @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Long") @DeleteMapping(path = "/{id}") public String deleteUser(@PathVariable Long id) { users.remove(id); return "success"; } }
@Data @ApiModel(value = "用户模型", description = "用户详细信息实体类") public class UserModel { @ApiModelProperty(value = "用户 ID") private Long id; @ApiModelProperty(value = "名字", allowableValues = "y0ngb1n, tony") private String name; @ApiModelProperty(value = "年龄", allowableValues = "range[1, 120]") private Integer age; @ApiModelProperty(value = "邮箱") private String email; }
此时可以启动项目进行验证是否成功集成 Swagger 2 了,启动项目后,在日志中可以看到 Swagger 为我们添加了访问端点 /v2/api-docs
:
... 2019-12-28 22:19:53.880 INFO 11935 --- [main] pertySourcedRequestMappingHandlerMapping : Mapped URL path [/v2/api-docs] onto method [public org.springframework.http.ResponseEntity<springfox.documentation.spring.web.json.Json> springfox.documentation.swagger2.web.Swagger2Controller.getDocumentation(java.lang.String,javax.servlet.http.HttpServletRequest)] ...
通过浏览器访问 http://localhost:8080/v2/api-docs
,可以发现返回的结果是一段 JSON 串,可读性非常差。幸运的是 Swagger 2 为我们提供了可视化的交互界面 SwaggerUI,下面我们就一起来试试吧。
同上面一样,在 pom.xml
中添加 Swagger UI 所需依赖:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
添加完成后,重新启动项目,然后通过浏览器访问 http://localhost:8080/swagger-ui.html
,便以看到下面就效果:
到这里就集成 Swagger 成功了,更多高阶的操作就等继续看文档或下面的参考链接进一步摸索了,祝学习愉快!
感谢您的阅读,本文由 杨斌的博客 版权所有。
如若转载,请注明出处:杨斌的博客( https://y0ngb1n.github.io?utm... )
项目已托管于 GitHub: y0ngb1n/spring-boot-samples ,欢迎 Star, Fork :kissing_heart: