• Spring Boot 学习笔记 源码地址
• Spring Boot 学习笔记(一) hello world
• Spring Boot 学习笔记(二) 整合 log4j2
• Spring Boot 学习笔记(三) 整合 MyBatis + Druid
• Spring Boot 学习笔记(四) 整合 Druid 监控
• Spring Boot 学习笔记(五) 整合 静态资源
• Spring Boot 学习笔记(六) 整合 RESTful 参数传递
• Spring Boot 学习笔记(七) 整合 Swagger2
• Spring Boot 学习笔记(八) 整合 Filter
• Spring Boot 学习笔记(九) 整合 多环境配置
• Spring Boot 学习笔记(十) Redis集群搭建
• Spring Boot 学习笔记(十一) 整合 Redis
• Spring Boot 学习笔记(十二) 整合 定时任务
• Spring Boot 学习笔记(十三) 整合 AOP
• Spring Boot 学习笔记(十四) 整合 Guava

---

1. 添加依赖

Swagger2 可以自动的根据代码生成接口文档。

添加依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

<!-- swagger api 管理工具 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

注意需要添加：spring boot web 依赖

2. 添加Swagger配置

修改 SpringbootApplication 启动类

@SpringBootApplication
@EnableSwagger2
@ComponentScan({"com.zdran.springboot"})
public class SpringbootApplication {

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

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("个人学习Spring Boot 的项目 APIs")
                .description("学习Spring Boot 中的 restful APIs")
                .termsOfServiceUrl("https://github.com/zdRan/learning")
                .contact(new Contact("个人开源项目组", 
                                    "https://github.com/zdRan/learning", 
                                    "cm.zdran@gmail.com"))
                .version("1.0")
                .build();
    }

默认访问地址是： http://localhost:9090/learning/swagger-ui.html

3. Swagger 注解

Swagger 有很多自定义的注解可以很方便的对接口进行描述

3.1 @Api

用在一个Controller上，swagger会将这个controller下的接口归为一组展示。
常用属性：

1. tags: 分组标签
2. value: 如果tags没有定义，value将作为tags使用
3. description： API的详细描述

个人建议的写法：

@Api(tags = "AccountController",description = "账户信息相关接口")
public class AccountController {
    //... ...
}

3.2 @ApiOperation

用在方法上。对该方法的描述信息

常用属性：

1. value: 对方法的简单描述，长度为120个字母，60个汉字。
2. notes: 对操作的详细说明。
3. httpMethod: 请求方式，可选值有”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。
4. code http 状态码，默认为200

个人建议的写法：

@ApiOperation(value = "获取账号信息",
        notes = "根据传入的参数 name 查询账号信息。",
        httpMethod= "GET")
@GetMapping("/get/{name}")
public AccountInfo getAccountByName(@PathVariable String name){
    //... ...
}

3.3 @ApiImplicitParams 与 @ApiImplicitParam

用在方法上。对参数列表的说明，这两个注解时连用的。ApiImplicitParams 内部有多个 ApiImplicitParam，每个 ApiImplicitParam 对应一个参数，常用属性：

1. name: 参数名称
2. value: 参数描述
3. paramType: 参数的传入（请求）类型，可选的值有path, query, body, header or form
4. dataType: 参数类型。可以为类名，也可以为基本类型（String，int、boolean等）
5. required: 是否是必填字段。

个人建议的写法：

    @ApiImplicitParams({
            @ApiImplicitParam(
                    name = "name",
                    value = "用户名",
                    paramType = "path",
                    dataType = "String",
                    required = true
            )
    })
    @GetMapping("/get/{name}")
    public AccountInfo getAccountByName(@PathVariable String name){
        //... ...
    }

3.4 @ApiResponses 与 ApiResponse

用在方法上，对方法的返回值（响应结果）进行说明。ApiResponses内部有多个ApiResponse。
ApiResponse 常用属性：

1. code:http状态码
2. message：对应状态码的描述
3. response：返回值。如果是类名的话，需要类的全路径
4. responseContainer：如果返回类型为容器类型，可以设置相应的值。有效值为 “List”, “Set” or “Map”

个人建议的写法：

    @ApiResponses({
            @ApiResponse(
                    code = 200,
                    message = "成功",
                    response = com.zdran.springboot.dao.AccountInfo.class
            ),
            @ApiResponse(
                    code = 404,
                    message = "网络异常",
                    response = Exception.class
            )
    })
    @GetMapping("/get/{name}")
    public AccountInfo getAccountByName(@PathVariable String name){
        //... ...
    }

一般 404 的 response 值应该是自定义的异常返回对象。

3.4 @ApiModel 与 @ApiModelProperty

这两个注解是用在实体类上面的，对实体类和参数进行说明。

ApiModel: 用在类上面，对类进行说明，有两个属性

1. value: 类的别名，默认是类名
2. description： 类的详细描述

ApiModelProperty: 用在类的属性上，对属性进行说明。 常用属性：

1. value: 属性的描述
2. example: 属性的示例值

个人建议的写法：

@ApiModel(
        value = "AccountInfo",
        description = "用户信息实体类"
)
public class AccountInfo {

    @ApiModelProperty(
            value = "账户id",
            example = "123455",
            dataType = "Integer"
    )
    private Integer accountId;

    @ApiModelProperty(
            value = "用户名",
            example = "zdran",
            dataType = "String"
    )
    private String name;

配置这些基本上就可以了，再多的话，代码入侵就有点多了。