学习 Spring Boot(六):使用 SpringFox 生成接口文档

SpringFox 是构建在 Spring Web 基础上自动生成 JSON API 文档的开源项目。

添加依赖

编辑 pom.xml 文件,添加依赖:

<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>  

springfox-swagger2 使用 Swagger Version 2.0 说明。默认地址:/v2/api-docs

Swagger 说明是用于描述 RESTful API 的定义格式。

springfox-swagger-ui 通过 web jar 使用 Swagger UI。Swagger UI 提供了一个非常美观的界面查看 REST API 文档。默认地址:/swagger-ui.html

激活 Swagger

编辑 Application.java Spring Boot 应用入口类,因为使用的 swagger2,所以在类定义添加 @EnableSwagger2 注解:

@SpringBootApplication
@EnableSwagger2
@Import(ApplicationConfiguration.class)
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

定义 Docket

Docket stands for A summary or other brief statement of the contents of a document; an abstract.

编辑 ApplicationConfiguration.java 配置文件,一个最简单的 Docket Bean 配置如下所示:

@Configuration
public class ApplicationConfiguration {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .paths(paths())
                .build();
    }

    private Predicate<String> paths() {
        return or(
                regex("/v1.*")
        );
    }

}

在这个配置中,SpringFox 会为 /v1 路径下的所有控制器生成 RESTful API 文档。

控制器配置

springfox-core 库中提供了一系列的注解,方便在生成文档时,提供元数据信息。例如:接口的描述信息和参数的描述的信息。示例:

@Api(value = "用户信息")
@RestController
@RequestMapping("/v1/users")
public class UserController {

    private final static Logger logger = LoggerFactory.getLogger(UserController.class);

    @Autowired
    private UserService userService;

    @ApiOperation(value = "查询所有用户信息", response = User.class, responseContainer = "List")
    @RequestMapping(method = RequestMethod.GET)
    public List<User> queryAllUsers() {
        logger.debug("调用方法 queryAllUsers()");
        List<User> result = this.userService.queryAllUsers();
        logger.debug("方法 queryAllUsers() 返回 {}", result);
        return result;
    }

    @ApiOperation(value = "根据用户名查询用户信息", response = User.class, responseContainer = "List")
    @RequestMapping(value = "/name/{name}", method = RequestMethod.GET)
    public List<User> queryUsersByName(
            @ApiParam(value = "用户名", required = true) @PathParam("name") String name) {
        logger.debug("调用方法 queryUsersByName(String name)");
        List<User> result = this.userService.queryUsersByName(name);
        logger.debug("方法 queryUsersByName(String name)", result);
        return result;
    }

}

@Api 用于标注 Controller 类, @ApiOperation 用于标注 Controller 方法,@ApiParam 用于标注