使用SpringBoot整合Swagger2构建API

关于如何创建SpringBoot项目本文不在说明，自行百度即可
本人使用的springboot 2.1.0版本，Swagger 2.9.2版本
本文创作时间：2018-12–07

1 创建SpringBoot项目，添加Swagger2的jar包

pom.xml配置如下

<properties>
    <swagger.version>2.9.2</swagger.version>
</properties>

<dependencies>
    <!--Swagger工具-->
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency><!--添加Swagger依赖 -->
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency><!--添加Swagger-UI依赖 -->
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
    </dependency>
</dependencies>

2 新建Swagger2Config配置文件，代码如下

其中特别特别要注意的是里面配置了apis文件也就是controller包的路径，不然生成的文档扫描不到接口。

@Configuration
//用于开启Swagger
@EnableSwagger2
public class Swagger2Config {
    /**
     * 添加摘要信息(Docket)
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("标题：SpringBoot测试项目系统接口文档")
                        .description("描述：用于管理SpringBoot的接口,主要有以下功能模块...")
                        .contact(new Contact("FlyFish",null,null))
                        .version("版本号:1.0")
                        .build())
                .select()
                /** 扫描的包所在位置 */
                .apis(RequestHandlerSelectors.basePackage("com.springboot.api.web.restcontroller"))
                /** 扫描的 URL 规则  */
                .paths(PathSelectors.any())
                .build();
    }

}

3 Swagger2的使用

PersonRestController代码如下

package com.springboot.api.web.restcontroller;
@Api(value = "PersonRestController", description = "用户信息管理测试模块")
@RestController
public class PersonRestController {
    /**
     * Spring Data JPA 已自动为你注册 bean，所以可自动注入
     */
    @Autowired
    PersonRepository personRepository;

    @Autowired
    PersonService personService;

    /**
     * @ApiOperation 描述方法用途
     */
    @ApiOperation(value = "保存用户信息", notes = "用于保存用户的信息")
    /** @ApiImplicitParam 描述放的参数 */
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String", required = true),
            @ApiImplicitParam(name = "address", value = "用户地址"),
            @ApiImplicitParam(name = "age", value = "用户年龄", dataType = "Integer")
    })
    @RequestMapping(value = "/save", method = RequestMethod.GET)
    public Person save(String name, String address, Integer age) {
        Person person = new Person(null, name, age, address);
        Person p = personRepository.save(person);
        return p;
    }

    /**
     * 测试 回滚
     */
    @ApiOperation(value = "回滚数据", notes = "用户测试回滚")
    @GetMapping("/rollback")
    public Person rollback(Person person) {
        Person personWithRollBack = personService.savePersonWithRollBack(person);
        return personWithRollBack;
    }
}

person代码

//@Entity注解指明这是一个和数据库表映射的实体类。
@Entity
/**
 * @ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
 * value–表示对象名
 * description–描述
 * */
@ApiModel(value = "PerSon实体对象", description = "用于存放Person对象的数据")
public class Person {

    /**
     * @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
     * value–字段说明
     * name–重写属性名字
     * dataType–重写属性类型
     * required–是否必填
     * example–举例说明
     * hidden–隐藏
     */
    /**
     * id
     * */
    @ApiModelProperty(name = "id", value = "用户id",dataType = "Long",example = "18",hidden = false)
    private Long id;
    /**
     * 姓名
     */
    /**
     * ①此处使用JSR-303注解来校验数据。
     */
    @Size(max = 4, min = 2)
    @ApiModelProperty(name = "name", value = "用户姓名",dataType = "String",example = "风羽",hidden = false)
    private String name;
    /**
     * 年龄
     */
    @ApiModelProperty(name = "age", value = "用户年龄",dataType = "Integer",example = "18",hidden = false)
    private Integer age;
    /**
     * 地址
     */
    @ApiModelProperty(name = "address", value = "用户地址",dataType = "String",example = "天空之城",hidden = false)
    private String address;
}

现在启动项目就可以了，然后访问Swagger默认网址就可以查看接口了
http://localhost:8080/swagger-ui.html#/

如下图

由于做了一些修改，所以导致展示界面于最后代码不一致，但是功能还是一样的

一些注解的说明

@Api 修饰整个类，描述Controller的作用
    value 类名称（目前没发现效果显示） 
    description 类说明
@ApiIgnore 用于类或者方法上，可以不被swagger显示在页面上
@ApiOperation 展示每个API基本信息
    value api名称
    notes 备注说明
@ApiImplicitParam 用于规定接收参数类型、名称、是否必须等信息
    name 对应方法中接收参数名称
    value 备注说明
    required 该字段是否必须 boolean
    paramType 参数类型 body、path、query、header、form中的一种 
        body 使用@RequestBody接收数据 POST有效
        path 在url中配置{}的参数
        query 普通查询参数 例如 ?query=q ,jquery ajax中data设置的值也可以，例如 {query:”q”},springMVC中不需要添加注解接收
        header 使用@RequestHeader接收数据
    form 笔者未使用，请查看官方API文档
    dataType 数据类型，如果类型名称相同，请指定全路径，例如 dataType = “java.util.Date”，springfox会自动根据类型生成模型
@ApiImplicitParams 包含多个@ApiImplicitParam
@ApiParam 对单独某个参数进行说明，使用在类中或者controller方法中都可以。注解中的属性和上面列出的同名属性作用相同
以上为主要常用的注解介绍，请结合springfox使用查看
@ApiModel  用于类 ；表示对类进行说明，用于参数用实体类接收 
    value–表示对象名 
    description–描述 
    都可省略 
@ApiModelProperty 对模型中属性添加说明，
    value 参数名称
    required 是否必须 boolean
    hidden 是否隐藏 boolean 
    其他信息和上面同名属性作用相同，hidden属性对于集合不能隐藏，目前不知道原因
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiError ：发生错误返回的信息