1. 引言
随着微服务架构体系的发展和应用, 为了前后端能够更好的集成与对接,同时为了项目的方便交付,每个项目都需要提供相应的API文档。
传统的API文档编写存在以下几个痛点:
- 对API文档进行更新的时候,需要通知前端开发人员,导致文档更新交流不及时;
- API接口返回信息不明确
- 缺乏在线接口测试,通常需要使用相应的API测试工具,比如postman、SoapUI等
- 接口文档太多,不便于管理
为了解决传统API接口文档维护的问题,为了方便进行测试后台Restful接口并实现动态的更新,因而引入Swagger接口工具。
Swagger具有以下优点:
- 功能丰富:支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
- 及时更新:开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
- 整合简单:通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。
当然也不能说Swagger就一定是完美的,它也有缺点,最明显的就是代码移入性比较强。
2. Swagger 2.0 集成配置
1. 添加Swagger2的Maven依赖
在Spring Boot项目中需要添加的依赖为Swagger 2核心包和swagger-ui界面包。
... 项目其他依赖包 ...
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
2. 创建Swagger2配置文件
package com.gayond.hurricane.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.garyond.hurricane.rest")) // 配置需要扫描的包路径
.paths(PathSelectors.any())
.build();
//.globalOperationParameters(pars);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("身份认证服务")
.description("提供统一的身份认证与身份验证服务")
.termsOfServiceUrl("http://www.baidu.com")
.version("0.0.1")
.build();
}
}
说明:
- 用 @Configuration 注解该类,等价于在Spring XML配置文件中beans配置;
- 用 @Bean 标注方法等价于Srping XML配置文件中的bean配置。
3. Spring Boot主应用中启用Swagger配置
需要在Spring Boot主应用中添加 @EnableSwagger2 注解说明启用Swagger服务
package com.garyond.hurricane.myservice;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class JwtServiceApplication {
public static void main(String[] args) {
SpringApplication.run(JwtServiceApplication.class, args);
}
}
3. Restful接口定义与展示
1. 在Spring Controller中使用Swagger注解
package com.garyond.hurricane.rest;
import com.garyond.hurricane.myservice.annotation.RequiredPerms;
import com.garyond.hurricane.myservice.controller.BaseController;
import com.garyond.hurricane.myservice.entity.JsonResult;
import com.garyond.hurricane.myservice.model.User;
import com.garyond.hurricane.myservice.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
/**
* 用户操作Restful接口
*
* @author Garyond
* @version 1.0
*/
@RestController
@Api(value = "/v1/user", description = "用户CRUD操作接口")
@RequestMapping("/v1/user")
public class UserRestController extends BaseController{
@Autowired
private UserService userService;
/**
* 检索用户信息
*
* @return
*/
@RequestMapping(value = "/query", method = {RequestMethod.GET})
@RequiredPerms("user:list")
@ApiOperation(value="根据用户名查询用户信息", notes="根据用户名查询用户信息")
public @ResponseBody JsonResult queryUsers(@ApiParam(name="username", value = "用户名", required = true) @RequestParam("username") String username) {
if (null == username || StringUtils.isBlank(username)) {
return this.renderError("用户名不能为空");
}
User user = userService.getUserByUsername(username);
if (null != user) {
return this.renderSuccess(user);
} else {
return this.renderError("无用户数据");
}
}
/**
* 获取所有用户信息
*
* @return
*/
@RequestMapping(method = {RequestMethod.GET})
@RequiredPerms("user:list")
@ApiOperation(value="获取用户列表", notes="获取用户列表")
public @ResponseBody JsonResult listUsers() {
List userList = userService.findAll();
if (null != userList && userList.size() > 0) {
return this.renderSuccess(userList);
} else {
return this.renderError("无用户数据");
}
}
/**
* 获取用户信息
*
* @param userId
* @return
*/
@RequestMapping(value = "/{userId}",method = {RequestMethod.GET})
@RequiredPerms("user:list")
@ApiOperation(value="根据UserId获取用户信息", notes="根据UserId获取用户信息")
@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "String", paramType = "path")
public @ResponseBody JsonResult getUser(@PathVariable("userId") String userId) {
User user = userService.getUserById(userId);
if (null != user) {
return this.renderSuccess(user);
} else {
return this.renderError();
}
}
/**
* 保存用户信息
*
* @param user
* @return
*/
@RequestMapping(method = {RequestMethod.POST})
@RequiredPerms("user:add")
@ApiOperation(value="添加用户信息", notes="添加用户信息")
@ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User")
public @ResponseBody JsonResult saveUser(User user) {
userService.save(user);
return this.renderSuccess();
}
/**
* 更新用户信息
*
* @param user
* @return
*/
@RequestMapping(method = {RequestMethod.PUT})
@RequiredPerms("user:update")
@ApiOperation(value="更新用户信息", notes="更新用户信息")
@ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User")
public @ResponseBody JsonResult updateUser(User user) {
userService.update(user);
return this.renderSuccess();
}
/**
* 删除用户信息
*
* @param userId
* @return
*/
@RequestMapping(value = "/{userId}", method = {RequestMethod.DELETE})
@RequiredPerms("user:list")
@ApiOperation(value="根据UserId删除用户信息", notes="根据UserId删除用户信息")
@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "String", paramType = "path")
public @ResponseBody JsonResult removeUser(@PathVariable("userId") String userId) {
userService.removeByUserId(userId);
return this.renderSuccess();
}
}
2. 查看Swagger 2文档
启动SpringBoot项目,访问 http://localhost:8080/swagger-ui.html
4. Swagger 2常用注解说明
Swagger 2通过注解表明该API接口会生成文档,包括接口名称、请求方法、请求参数、返回信息的等等。
Swagger 2.0使用的注解及其说明:
- @Api:用在类上,说明该类的作用。
- @ApiOperation:注解来给API增加方法说明。
- @ApiImplicitParams : 用在方法上包含一组参数说明。
- @ApiImplicitParam:用来注解来给方法入参增加说明。
- @ApiResponses:用于表示一组响应
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
作用范围 | API | 使用位置 |
---|---|---|
对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
协议集描述 | @Api | 用于controller类上 |
协议描述 | @ApiOperation | 用在controller的方法上 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses里边 |
非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
关于Swagger注解的使用可参考Swagger常用注解说明
更多信息可以参考【Swagger官方手册】
以下是个人微信公众号, 用于学习与交流, 欢迎大家关注。