本节内容:
- 什么是Swaggger
- Springfox与Swagger的关系
- SpringMVC集成springfox-swagger2
一、什么是Swaggger
Swagger是一个流行的API开发框架,这个框架以“开放API声明”(OpenAPI Specification,OAS)为基础,对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,几乎支持所有语言)。
二、Springfox与Swagger的关系
OSA本身是一个API规范,它用于描述一整套API接口,包括一个接口是GET还是POST请求啊,有哪些参数哪些header啊,都会被包括在这个文件中。它在设计的时候通常是YAML格式,这种格式书写起来比较方便,而在网络中传输时又会以json形式居多,因为json的通用性比较强。
由于Spring的流行,Marty Pitt编写了一个基于Spring的组件swagger-springmvc,用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来,同时springfox也是一个新的项目,本文使用的是其中的一个组件springfox-swagger2。
如果想要集成swagger-springmvc就相对麻烦一点,因为要把它的静态文件copy到自己的项目中。springfox-swagger2依然是依赖OSA规范文档,也就是一个描述API的json文件,而这个组件的功能就是帮助我们自动生成这个json文件,我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来,用一种更友好的方式呈现出来。
三、SpringMVC集成springfox-swagger2
1. 添加依赖的jar包
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
2. spring-mvc.xml中添加映射静态的配置
<mvc:default-servlet-handler />
3. 配置文件
在源码包里建一个config目录,并在里面创建一个SwaggerConfig.java文件,这是一个spring的配置文件,所以位置和文件名都影响不大。
SwaggerConfig.java
package com.spring.learn.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Created by jkzhao on 1/19/18.
*/
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.spring.learn.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring 中使用Swagger2构建RESTful APIs")
.termsOfServiceUrl("http://www.cnblogs.com/zhaojiankai/")
.description("springmvc swagger2")
.contact(new Contact("zhaojiankai", "http://www.cnblogs.com/zhaojiankai/", "743833196@qq.com"))
.version("1.1")
.build();
}
}
这个SwaggerConfig类有四个注解,其中,@Configuration是Spring的注解,而@EnableSwagger2则是用来启动Swagger支持,表示这是一个Spring Swagger的配置文件。
之后,定义了一个Bean方法createRestApi,Spring中名字并不重要,重要的是它返回一个Docket类,DocumentationType.SWAGGER_2作为Docket构造方法的参数,指定了所用的swagger版本2.0,官网上已经在预告3.0版本了。而之后的apiInfo则是调用接下来的apiInfo函数,来创建Docket的信息。apiInfo函数采用ApiInfoBuilder来创建ApiInfo类。
然后运行项目,在浏览器输入:http://{ip}:{port}/{projectname}/swagger-ui.html
它会把按照controller,把所有的接口都加载进来。
我的目录结构如图:
然后,就是接口名称和参数的说明:
常用注解:
- @Api()用于类名
- @ApiOperation()用于方法名
- @ApiParam()用于参数说明
- @ApiModel()用于实体类
- @ApiModelProperty用于实体类属性
更详细的说明请参见官方注解说明文档
【示例】:
ApiController.java
@Controller
@RequestMapping("/api")
@Api(value = "api接口", description="用户相关操作")
public class ApiController {
@Autowired
private UserService userService;
@RequestMapping(value = "/user", method = {RequestMethod.GET})
@ApiOperation(value = "用户查询服务", notes = "根据传过来的user_id来查询用户")
public String getUserById(@ApiParam(value = "用户id") String user_id, ModelMap map){
User user = userService.getUserById(user_id);
map.put("user", user);
return "success";
}
}
User.java
@ApiModel(value = "用户")
public class User {
private String user_id;
@ApiModelProperty(value = "用户名")
private String user_name;
@ApiModelProperty(value = "密码")
private String password;
...
重新运行起项目,访问效果如下: