Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档

1、添加Swagger2依赖

在pom.xml中加入Swagger2的依赖

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

编写Swagger2配置类

/**
 * ${DESCRIPTION}
 *
 * @author Ricky Fung
 * @create 2017-01-02 23:53
 */
@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.bytebeats.springboot.ch2.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("Ricky", "http://www.bytebeats.com", "[e-mail]"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

3、编写Controller

这里开始编写自己的RESTful Controller，跟正常开发没什么区别。主要是接口方法上面新增了几个注解：

• 通过@ApiOperation注解来给API增加说明
• 通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
• 通过@ApiIgnore来忽略那些不想让生成RESTful API文档的接口

4 完成上述代码后，打包Spring Boot程序并启动，打开浏览器访问：http://localhost:8080/swagger-ui.html，就能看到前文所展示的RESTful API的页面。

5、Swagger常用注解：

• @Api 标识Controller使用swagger.
• @ApiImplicitParam 表示一个隐式的请求参数，即请求方法中没有显示绑定参数名称.
• @ApiImplicitParams 表示隐式参数列表.
• @ApiModel 描述请求或返回对象的额外信息.
• @ApiModelProperty 描述或者生成ApiModel的成员变量.
• @ApiOperation 描述一个Http请求方法
• @ApiParam 描述显示的请求参数.
• @ApiResponse 描述可能的返回对象.
• @ApiResponses 表示返回对象列表.
• @Authorization 申明认证信息.
• @ResponseHeader 表示返回头部信息.

github：https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#api