现在越来越多的应用都采用restful风格的开发模式来构建API,这样也有利于实现前后端分离,前端进行数据展示,后端提供数据,前后端之间通过json的格式来进行数据传递。这时候前后端之间的交流就只有通过API来进行了,但是随着发布的API越来越多交流与测试就成了一个很麻烦的事情。
为了解决这类问题业界也提供各种解决方案,我们这里选用Swagger技术来解决这个问题,关于Swagger的介绍请参见官网Swagger,当然Swagger提供了java实现,因为我采用的spring boot所以选用springfox这个开源实现来集成Swagger。
软件环境
spring boot 2.0
首先需要引入依赖,我们看pom文件
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
下一步我们就要创建Swagger的配置类,参见以下代码
/**
* @author chengjian
* @date 2018/2/19
**/
@Configuration
@EnableSwagger2 //Enable swagger 2.0 spec
@ComponentScan(basePackageClasses = {
UserController.class
})
public class SwaggerConfiguration extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
@Bean
public Docket userApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("user-api")
.apiInfo(apiInfo())
.select()
.paths(userPaths())
.build();
}
private Predicate<String> userPaths() {
return regex("/user.*");
}
/**
* api 页面简介
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXX系统API")
.description("提供相应的数据调用api,仅供测试")
.version("1.0")
.build();
}
}
代码很简单,当然这只是最简单的Swagger配置
@EnableSwagger2 //Enable swagger 2.0 spec 这个注解说明我们采用的是最新的Swagger2版本
@ComponentScan(basePackageClasses = {UserController.class}
这个注解表明我们将UserController这个类纳入Swagger管理,如果有多个类要使用Swagger那么需要加入多个累并以逗号分隔。
addResourceHandlers()这个方法是定义了Swagger页面的映射路径,如果不配置就没法跳转到相应的Swagger页面。
userApi()和userPaths()方法就定义了UserController具体的配置信息。
apiInfo()这个方法定义了Swagger相应的描述信息。
这样我们就完成了Swagger的基础配置
完成了Swagger的配置后我们需要定一个一个Controller来实现Swagger的跳转映射,因此我们创建了一个Controller
package com.spring.common.controller;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
@Controller
public class HomeController {
@RequestMapping("/")
public String home() {
System.out.println("homecontroller");
return "redirect:swagger-ui.html";
}
}
这里我们就定义了Swagger的映射和跳转。
至此我们就完成了Swagger的基本使用,其实Swagger包含了很多的使用方法,例如安全之类的可以参见springfox的官方文档springfox。
这里的简单的配置我也有代码实现,可以参考我的代码spring