前言

在项目开发的过程中，我们通常需要编写API文档来更好地描述我们的接口，而Swagger则是通过特定的注解来自动完成这些API的编写的一个工具。由于Swagger的强大的功能，Spring逐渐将其集成，因此有了Spring-Swagger，并最终演变成Springfox。Springfox的大致原理就是，在项目启动的过程中，spring上下文的初始化的过程，框架自动根据配置家在一些swagger相关的bean到当前的上下文，并且自动扫描系统中可能需要生成的api文档的那些类，并生成响应的信息缓存起来。一般的都会扫描控制层Controller类，根据这些Controller类中的功能方法自动生成API接口文档。

MAVEN引入

首先在IDEA中新建工程，在pom.xml中添加如下代码进行引入。

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

版本号可以根据需要自行修改。

Springboot中的配置

在项目中新建一个配置类 Swagger2Configuration。代码如下：

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket buildDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(buildApiInf())
            .select()
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo buildApiInf(){
        return new ApiInfoBuilder()
            .title("SwaggerTitle")
            .description("swagger description")
            .build();

    }
}

使用@EnableSwagger2注解开启对swagger2.0以上版本的支持。

常用注解

@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置" 

@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否为必须
paramType：参数放在哪个地方
    · header --> 请求参数的获取：@RequestHeader
    · query --> 请求参数的获取：@RequestParam
    · path（用于restful接口）--> 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用）    
dataType：参数类型，默认String，其它值dataType="Integer"       
defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性