实用小工具——SpringBoot整合Swagger

SpringBoot整合Swagger

前后端分离后，维护接口文档基本上是必不可少的工作。一个理想的状态是设计好后，接口文档发给前端和后端，大伙按照既定的规则各自开发，开发好了对接上了就可以上线了。当然这是一种非常理想的状态，实际开发中却很少遇到这样的情况，接口总是在不断的变化之中，有变化就要去维护，做过的小伙伴都知道这件事有多么头大！还好，有一些工具可以减轻我们的工作量，Swagger2就是其中之一。

API详细说明

注释汇总

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在出入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

引入依赖

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

开启Swagger2

 @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ytzl.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合swagger")
                        .description("SpringBoot整合swagger,详细描述信息.....")
                        .version("1.0")
                        .contact(new Contact("test1","http://localhost:8080/test1","8888@gmail.com"))
                        .license("百度")
                        .licenseUrl("http://www.baidu.com")
                        .build()
                );
    }

​
这里提供一个配置类，首先通过@EnableSwagger2注解启用Swagger2，然后配置一个Docket Bean，这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等…
如此，Swagger2就算配置成功了，非常方便。
Swagger UI常用URL：http://localhost:8080/swagger-ui.html 输入链接能够看到如下页面，Congratulations！配置成功！

参数解释

1. @Api注解可以用来标记当前Controller的功能。
2. @ApiOperation注解用来标记一个方法的作用。
3. @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
4. 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
5. 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
6. 如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：

@ApiModel
@Data
@NoArgsConstructor
@AllArgsConstructor
public class TbDepartment implements Serializable {
    /**
     * 部门id
     */
    @ApiModelProperty(value = "部门id")
    private Long id;
    /**
     * 部门名称
     */
    @ApiModelProperty(value = "部门名称")
    private String department_name;
    /**
     * 创建时间
     */
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
    /**
     * 更新时间
     */
    @ApiModelProperty(value = "更新时间")
    private Date updateTime;
}

@ApiModel
@Data
@NoArgsConstructor
@AllArgsConstructor
public class TbEmployee implements Serializable {
    /**
     * id
     */
    @ApiModelProperty(value = "id")
    private Long id;
    /**
     * 员工姓名
     */
    @ApiModelProperty(value = "员工姓名")
    private String employee_name;
    /**
     * 员工年龄
     */
    @ApiModelProperty(value = "员工年龄")
    private Long employee_age;
    /**
     * 员工性别
     */
    @ApiModelProperty(value = "员工性别")
    private String employee_gender;
    /**
     * 部门ID
     */
    @ApiModelProperty(value = "部门ID")
    private String department_id;
    /**
     * 创建时间
     */
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
    /**
     * 更新时间
     */
    @ApiModelProperty(value = "更新时间")
    private Date updateTime;
}

好了到这我们的教程也结束了😉
希望以上方法可以帮到您，祝您工作愉快！💖

👇
对您有帮助的话记点赞得收藏哦！👍
我是 沁禹 一个在互联网摸爬滚打的工具人 😛