Spring-Boot + Swagger2 自动生成API接口文档

spring-boot作为当前最为流行的Java web开发脚手架，相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端（b/s），也会服务于移动端。在实际开发过程中，这些接口还要提供给开发测试进行相关的白盒测试，那么势必存在如何在多人协作*享和及时更新API开发接口文档的问题。
假如你已经对传统的wiki文档共享方式所带来的弊端深恶痛绝，那么尝试一下Swagger2 方式，一定会让你有不一样的开发体验：

• 功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
• 及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
• 整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

Spring-Boot Swagger2 自动生成API接口文档

• 1添加pom依赖
  • 代码块
• 2将swagger-ui中的界面配置至spring-boot环境
  • 代码块
• 3配置API文档页基本信息
  • 代码块
• 4API文档编写示例
  • 代码块
• 5在线查看及测试API文档

1、添加pom依赖

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

2. 创建Swagger2配置文件

package com.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2")
                .description("首次尝试自动生成api文档为后期的前后端分离开发做准备")
                .termsOfServiceUrl("https://www.jianshu.com/u/2f60beddf923")
                .contact("WEN")
                .version("1.0")
                .build();
    }
}

3.实体类model

package com.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@ApiModel("用户实体")
@Data
public class User {
    /**
     * 用户Id
     */
    @ApiModelProperty("用户id")
    private int id;

    /**
     * 用户名
     */
    @ApiModelProperty(value = "用户姓名", example = "zhangdan", required = true)
    private String name;

    /**
     * 用户地址
     */
    @ApiModelProperty(value = "用户地址", example = "北京市海淀区", required = true)
    private String address;

    /**
     * 用户手机号
     */
    @ApiModelProperty(value = "用户手机号", example = "15689652367", required = true)
    private String phone;

    /**
     * 用户年龄
     */
     @ApiModelProperty(value = "用户年龄", example = "24", required = true)
     private Integer age;
}

4.接口开发

package com.controller;

import com.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Api(tags = "用户相关接口", description = "提供用户相关的Rest API")
public class UserController {

    @PostMapping("/add")
    @ApiOperation(value = "新增用户接口", notes = "手机号、密码都是必输项，年龄随边填，但必须是数字")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户名称", required = true, paramType = "query"),
            @ApiImplicitParam(name = "address", value = "用户地址", required = true, paramType = "query"),
            @ApiImplicitParam(name = "phone", value = "用户手机号", required = true, paramType = "query"),
            @ApiImplicitParam(name = "age", value = "用户年龄", required = true, paramType = "query", dataType = "Integer")
    })
    public String addUser(@RequestBody User user) {
        return user.toString();
    }

    @ApiOperation("通过id查找用户接口")
    @GetMapping("/find/{id}")
    public User findById(@PathVariable("id") int id) {
        return new User();
    }

    @ApiOperation("更新用户信息接口")
    @PutMapping("/update")
    @ApiResponses({
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
            @ApiResponse(code = 405, message = "未知错误")
    })
    public boolean update(@RequestBody User user) {
        return true;
    }
}

swagger界面显示

  

5. Swagger 2常用注解说明
Swagger 2通过注解表明该API接口会生成文档，包括接口名称、请求方法、请求参数、返回信息的等等。

Swagger 2.0使用的注解及其说明：@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
作用范围    API    使用位置
对象属性    @ApiModelProperty    用在出入参数对象的字段上
协议集描述    @Api    用于controller类上
协议描述    @ApiOperation    用在controller的方法上
Response集    @ApiResponses    用在controller的方法上
Response    @ApiResponse    用在 @ApiResponses里边
非对象参数集    @ApiImplicitParams    用在controller的方法上
非对象参数描述    @ApiImplicitParam    用在@ApiImplicitParams的方法里边
描述返回对象的意义    @ApiModel    用在返回对象类上