概述
随着前后端分离架构和微服务架构的流行，使用Spring Boot来构建RESTful API项目的场景越来越多。通常一个RESTful API就有可能要服务于多个不同的开发人员或开发团队：IOS开发、Android开发、Web开发甚至其他的后端服务等。
为了减少与其他团队平时开发期间的频繁沟通成本，常规方式是创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：
- 由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就非常吃力。
- 随着开发工作的进展，不断修改接口实现的时候，必须同步更新接口文档，而文档与代码又处于两个不同的媒介，很容易出现不一致。
- 开发人员完成接口开发后，需要进行测试和调试，此时就需要类似Postman工具软件或者在浏览器上安装类似功能的插件，才能进行测试。
为了解决上面的问题，这里使用Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合生成强大RESTful API文档。它既可以减少创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以在修改代码逻辑的同时方便的修改文档说明。
而且Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
一、Swagger2的使用
配置
- POM文件引入依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
- 在启动类同级，创建配置类：
@Configuration
@EnableSwagger2
public class Swagger {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() // 选择那些路径和api会生成document
.apis(RequestHandlerSelectors.basePackage("com.routon.datadisplayplatform.controller")) //对该路径下api进行监控
.paths(PathSelectors.any()) //对所有路径进行监控
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("大数据展示平台")
.description("大数据平台数据展示的RESTful APIs")
.contact("Dcl_Snow")
.version("1.0")
.build();
}
}
- 在Controller接口类中进行注释：
@Api(tags = "用户管理接口")
@RestController
@RequestMapping("/users")
public class UserController {
static Map<Long,User> users = Collections.synchronizedMap(new HashMap<Long, User>());
@ApiOperation(value="获取用户列表", notes="")
@RequestMapping(value = "/",method = RequestMethod.GET)
public List<User> getUserList(){
List<User> list = new ArrayList<>(users.values());
return list;
}
@ApiOperation(value="创建用户", notes="根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = false, dataType = "User")
@RequestMapping(value = "",method = RequestMethod.POST)
public String postUser(@ModelAttribute User user){
users.put(user.getId(),user);
return "success";
}
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value = "/{id}",method = RequestMethod.GET)
public User getUser(@PathVariable Long id){
return users.get(id);
}
@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = false, dataType = "User")
})
@RequestMapping(value = "/{id}",method = RequestMethod.PUT)
public String putUser(@PathVariable Long id, @ModelAttribute User user){
User user1 = users.get(id);
user1.setName(user.getName());
user1.setAge(user.getAge());
users.put(id,user1);
return "success";
}
@ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id){
users.remove(id);
return "success";
}
}
- 在实体类中进行注释：
@ApiModel(value = "User", description = "用户实体User")
@Gettter
@Setter
public class User {
@ApiModelProperty(value = "用户编号", name = "id")
private Long id;
@ApiModelProperty(value = "用户姓名", name = "username")
private String name;
@ApiModelProperty(value = "用户年龄", name = "年龄")
private Integer age;
}
参数解释
@Api：用在请求的Controller类上，修饰整个类，描述Controller的作用
tags="说明该类的作用，可以在UI界面上看到的注解"
@ApiOperation：用在请求的接口方法上，描述方法的作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数信息
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用在实体类中，描述实体类的信息等
@ApiModelProperty：描述实体类的属性
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
配置分组
public class Swagger {
@Bean
public Docket customDocket1(){
return newDocket(DocumentationType.SWAGGER_2)
.groupName("systemManager").apiInfo(apiInfo())
.select()
.paths(PathSelectors.ant("/sys/**"));
}
@Bean
public Docket customDocket2(){
return newDocket(DocumentationType.SWAGGER_2)
.groupName("userManager").apiInfo(apiInfo())
.select()
.paths(PathSelectors.ant("/user/**"));
}
}
二、SpringCloud的zuul网关使用swagger2
项目结构
image.png
zuul配置
在zuul网关module中，引入Swagger的依赖，然后创建Swagger的配置文件SwaggerConfig：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Autowired
private DiscoveryClientRouteLocator discoveryClientRouteLocator;
@Primary
@Bean
public SwaggerResourcesProvider swaggerResourcesProvider() {
return () -> {
List<SwaggerResource> resources = new ArrayList<>();
for (Route route : discoveryClientRouteLocator.getRoutes()) {
resources.add(createResource(route.getLocation(),route.getId(), "2.0"));
}
return resources;
};
}
private SwaggerResource createResource(String name, String location, String version) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation("/v2/api-docs");
swaggerResource.setSwaggerVersion(version);
return swaggerResource;
}
}
就是在zuul中定义了一个路由规则，来获取2个服务的地址。
服务配置
创建了serviceOne和serviceTwo两个服务module，引入Swagger的依赖，然后创建Swagger的配置文件Swagger2：
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("cn.com.routon"))
.paths(PathSelectors.any())
.build()
.apiInfo(
new ApiInfoBuilder()
.version("1.0")
.title("Original Service API")
.description("Original Service API v1.0")
.build()
);
}
}
因为没有在项目中添加任何接口，所以其显示的是SpringBoot的默认Controller的API。
三、Spring4All封装Swagger2的使用
配置
- POM文件引入依赖：
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.1.RELEASE</version>
</dependency>
- 在启动类中使用注解开启swagger：
@EnableSwagger2Doc
@SpringBootApplication
public class SwaggerexampleApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerexampleApplication.class, args);
}
}
- 在application.properties文件配置相关内容：
//标题
swagger.title=大数据展示平台项目
//描述
swagger.description=Data Display Platform
//版本
swagger.version=1.0.RELEASE
//维护人
swagger.contact.name=Dcl_Snow
//维护人URL
swagger.contact.url=https://www.cnblogs.com/dcl-snow/
//维护人邮箱
swagger.contact.email=Dcl_Snow@163.com
//swagger扫描的基础包，默认：全扫描
swagger.base-package=com.example.swaggerexample
//需要处理的基础URL规则，默认：/**
swagger.base-path=/**
- 在Controller接口类中进行注释，@Api、@ApiOperation是API的说明内容，@ApiImplicitParam、@ApiModel、@ApiModelProperty是参数的说明内容：
@Api(tags = "用户管理接口")
@RestController
@RequestMapping("/users")
public class UserController {
static Map<Long,User> users = Collections.synchronizedMap(new HashMap<Long, User>());
@ApiOperation(value="获取用户列表", notes="")
@RequestMapping(value = "/",method = RequestMethod.GET)
public List<User> getUserList(){
List<User> list = new ArrayList<>(users.values());
return list;
}
@ApiOperation(value="创建用户", notes="根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = false, dataType = "User")
@RequestMapping(value = "",method = RequestMethod.POST)
public String postUser(@ModelAttribute User user){
users.put(user.getId(),user);
return "success";
}
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value = "/{id}",method = RequestMethod.GET)
public User getUser(@PathVariable Long id){
return users.get(id);
}
@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = false, dataType = "User")
})
@RequestMapping(value = "/{id}",method = RequestMethod.PUT)
public String putUser(@PathVariable Long id, @ModelAttribute User user){
User user1 = users.get(id);
user1.setName(user.getName());
user1.setAge(user.getAge());
users.put(id,user1);
return "success";
}
@ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id){
users.remove(id);
return "success";
}
}
