Java Spring Boot swagger2 配置

0.我的环境

IntelliJ IDEA
Spring Boot

1.添加swagger2的依赖

在pom.xml中添加如下内容

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

因为我的IDE是IntelliJ IDEA，添加之后会自动下载依赖包
如果不能自动下载的话，也可以自己下载

maven依赖包都是在这里下载的：
https://repo.maven.apache.org/maven2
与swagger2相关的包在这里：https://repo.maven.apache.org/maven2/io/springfox/

2.创建Swagger2配置类

在Application.java同级创建Swagger2的配置类Swagger2Config

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("设置自己的标题")
                .description("添加描述文字")
                .termsOfServiceUrl("http://localhost:8080")//相关网站地址
                .version("2.0") //版本号，在标题旁边
                .build();
    }
}

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

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

3.运行网站

假设网站的base url是：http://localhost:8080/
那么swagger-ui的url就是：http://localhost:8080/swagger-ui.html#/

4.常用注解

@Api 控制器说明

@Api(value = "Swagger Test Control", 
     description = "演示Swagger用法的Control类", 
     tags = "Swagger Test Control Tag")
// 写在controller类定义上方

@ApiOperation 控制器操作说明

@ApiOperation(value="创建用户", notes="根据User对象创建用户")
// 写在REST接口上方

@ApiResponses 返回状态码说明

@ApiResponses({
    @ApiResponse(code = 400, message = "权限不足"),
    @ApiResponse(code = 500, message = "服务器内部异常") }
)
// 写在REST接口上方

@ApiImplicitParams 参数说明

@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "ID", dataType = "Long"),
    @ApiImplicitParam(name = "user", value = "用户", dataType = "User")
})
// 写在REST接口上方

@ApiModel和@ApiModelProperty 类及其属性

@ApiModel( description = "学生")
public class Student {
    @ApiModelProperty(value = "主键id")
    private String id;
    @ApiModelProperty(value = "名称", required = true)
    private String name;
    @ApiModelProperty(value = "年龄", required = true)
    private int age;
}

可能遇到的问题

具体报错信息我忘了，大概是ClassNotFound…Bean生成出错

原因：

依赖包的版本不同

解决：

仔细看看pom.xml中是否有以下依赖包

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-spring-web</artifactId>
    <version>2.9.2</version>
</dependency>

再回顾一下第一步添加的swagger2依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

发现了吗，它们同属于io.springfox
所以三者的version必须相同，否则可能因为版本间的差异而造成错误。
https://repo.maven.apache.org/maven2
再给一次maven库链接，maven依赖包都是在这里下载的，学会在这个库里去找自己需要的，在网上找教程学的时候，就可以在这里找到最新版本，而不必担心因为教程和自己的环境不同而导致的版本问题

参考链接：http://blog.didispace.com/springbootswagger2/