- 引言
随着微服务架构体系的发展和应用, 为了前后端能够更好的集成与对接,同时为了项目的方便交付,每个项目都需要提供相应的API文档。
传统的API文档编写存在以下几个痛点:
对API文档进行更新的时候,需要通知前端开发人员,导致文档更新交流不及时;
API接口返回信息不明确
缺乏在线接口测试,通常需要使用相应的API测试工具,比如postman、SoapUI等
接口文档太多,不便于管理
为了解决传统API接口文档维护的问题,为了方便进行测试后台Restful接口并实现动态的更新,因而引入Swagger接口工具。
Swagger具有以下优点:
功能丰富:支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
及时更新:开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
整合简单:通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。
当然也不能说Swagger就一定是完美的,它也有缺点,最明显的就是代码移入性比较强。
- Swagger 2.0 集成配置
- 添加Swagger2的Maven依赖
- 创建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配置。
- 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);
}
}
- Restful接口定义与展示
- 在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();
}
-
}
- 查看Swagger 2文档
启动SpringBoot项目,访问 http://localhost:8080/swagger-ui.html
- 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官方手册】
作者:夜影风
来源:优快云
原文:https://blog.youkuaiyun.com/garyond/article/details/80189921
版权声明:本文为博主原创文章,转载请附上博文链接!