Spring Boot中使用Swagger2构建强大的RESTful API文档

Swagger可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

添加maven依赖:

<!-- Swagger -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.7.0</version>
</dependency>

 swagger配置文件:

在Application.java同级创建Swagger2的配置类SwaggerConfig，也可在新建packageconfig里创建。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.mydearest.controller")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多信息请关注博客：http://www.cnblogs.com/cosyer/")
                .termsOfServiceUrl("http://www.cnblogs.com/cosyer/").version("1.0").build();
    }

}

如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

我们可以通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

@Api：用在类上，说明该类的作用

@ApiIgnore：添加注解不扫描该controller

@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

示例:

// 添加书籍
@ResponseBody
@ApiOperation(value = "添加书籍", notes = "")
@ApiImplicitParams({ @ApiImplicitParam(paramType="query",name = "bookName", value = "书籍名称", required = true, dataType = "String"),
@ApiImplicitParam(paramType="query",name = "descripation", value = "描述", required = true, dataType = "String"),
@ApiImplicitParam(paramType="query",name = "mark", value = "评分", required = true, dataType = "String") })
@RequestMapping(value = "/addBook", method = RequestMethod.POST)
public String addBook(HttpServletRequest req) {
    String bookId = Get8uuid.generateShortUuid();
    String bookName = req.getParameter("bookName");
    String descripation = req.getParameter("descripation");
    String mark = req.getParameter("mark");
    manageMapper.addBook(bookId, bookName,descripation, mark);
    Map result = new HashMap();
    result.put("添加成功", "success");
    return JSON.toJSONString(result);
}

注意swagger需要返回jso字符串数据否则会报错。

页面:

springboot工程需要将接口页面用到的静态页面放到static目录下。