使用springfox整合SpringMVC和Swagger

Swagger 是一系列对 RESTful 接口进行规范描述和页面展示的工具. 通过 springfox-swagger 将 Swagger 与 Spring-MVC 整合, 可从代码中的注解获取信息, 并生成相应的文档. 效果如下所示.

目前 Swagger 的 api 版本规范已经更新到 2.0 版本, 中文网络上基本上都是 1.0 的 api 版本规范的教程. 捣鼓了一天终于搞定了, 这两者区别还是有的.

先添加依赖

<!--springfox-swagger需要的最小依赖 start-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>

</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>${version.jackson}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>${version.jackson}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>${version.jackson}</version>
</dependency>

<!--petStore是官方提供的一个代码参考, 可用于后期写文档时进行参考, 可不加-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-petstore</artifactId>
    <version>2.5.0</version>
</dependency>
<!--end-->

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.11</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.17</version>
    <type>jar</type>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>${version.spring}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>${version.spring}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>${version.spring}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-beans</artifactId>
    <version>${version.spring}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>${version.spring}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <version>${version.spring}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context-support</artifactId>
    <version>${version.spring}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-test</artifactId>
    <version>${version.spring}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-log4j12</artifactId>
    <version>1.7.5</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>1.7.5</version>
</dependency>

springfox-swagger2 可以将代码中的注解转换为符合 Swagger 的 API 规范的 swagger.json 文件, springfox-swagger-ui 提供了将 swagger.json 转换为 html 页面的服务.

最精简的 springfox 配置

Docket 对象为 spring-fox 提供了配置信息, ApiInfo 为生成的文档提供了元数据信息. 两者都使用这里我们仅仅使用最小配置, 两者均为默认配置. @EnableSwagger2 表示启用 Swagger.

@Configuration
@EnableSwagger2
public class MySwaggerConfig {
}

然后再在 spring-component.xml 配置文件中将这个类注册成 bean, 用于启用配置

<bean class="com.swagger.doc.MySwaggerConfig" />

这样就开启了 springfox 和 swagger.

spring-mvc.xml：

<mvc:annotation-driven/>

<context:component-scan base-package="com.swagger.doc"/>

<mvc:default-servlet-handler/>
<bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="prefix" value="/WEB-INF/views/"/>
    <property name="suffix" value=".jsp"/>
</bean>

springfox 的注解

写一个简单的 Controller

@Api(value = "User控制器")
@Controller
@RequestMapping("/user")
public class UserController {
    @ApiOperation(value = "根据用户id查询用户信息", httpMethod = "GET", produces = "application/json")
    @ApiResponse(code = 200, message = "success", response = Result.class)
    @ResponseBody
    @RequestMapping(value = "queryUserById", method = RequestMethod.GET, produces = "application/json")
    public Result queryUserById(@ApiParam(name = "userId", required = true, value = "用户Id") @RequestParam("userId") int userId, HttpServletRequest request) {
        User user = new User(userId, "haoyifen", 24);
        Result result = new Result();
        result.setCode(0);
        result.setData(user);
        result.setMessage("success");
        return result;
    }
}

常用的几个用于生成文档的注解如下:
- @Api 表示该类是一个 Swagger 的 Resource, 是对 Controller 进行注解的
- @ApiOperation 表示对应一个 RESTful 接口, 对方法进行注解
- @ApiResponse 表示对不同 HTTP 状态码的意义进行描述
- @ApiParam 表示对传入参数进行注解

结果验证:

最后工程结构如下:

访问 http://localhost:8080/swagger-ui.html 就可以看到API文档, 并且能够进行在线的操作.

相关资源:
springfox官方文档: https://springfox.github.io/springfox/docs/snapshot/#introduction