Swagger2

简介

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

为什么使用Swagger

当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发

模式 下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上

的文档都是 后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种

文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了

一个全新的维护 API 文档的方式，下面我们就来了解一下它的优点：

1.代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保

证了文 档的时效性。

2.跨语言性，支持 40 多种语言。

3.Swagger UI 呈现出来的是一份可交互式的 API 文档， 我们可以直接在文档页面尝试 API 的调

用，省去了准备复杂的调用参数的过程。

快速入门

引入依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>

启用Swagger2

在启动类上或者配置类加 @EnableSwagger2 注解

@SpringBootApplication
@MapperScan("com.zzq.mapper")
@EnableScheduling
@EnableSwagger2
public class ZZQBlogApplication {
    public static void main(String[] args) {
        SpringApplication.run(ZZQBlogApplication.class,args);
    }
}

测试

访问： http://localhost:7777/swagger-ui.html 注意其中 localhost 和 7777 要调整成实际项目的域名和端 口号。

具体配置

Controller配置

@Api 注解

属性介绍：

tags 设置标签

description 设置描述信息

@RestController
@RequestMapping("/comment")
@Api(tags = "评论",description = "评论相关接口")
public class CommentController {
}

接口配置

接口描述配置 @ApiOperation

@GetMapping("/linkCommentList")
@ApiOperation(value = "友链评论列表",notes = "获取一页友链评论")
public ResponseResult linkCommentList(Integer pageNum,Integer pageSize){
return
commentService.commentList(SystemConstants.LINK_COMMENT,null,pageNum,pageSize);
}

接口参数描述

@ApiImplicitParam 用于描述接口的参数，但是一个接口可能有多个参数，所以一般与

@ApiImplicitParams 组合使用。

@GetMapping("/linkCommentList")
@ApiOperation(value = "友链评论列表",notes = "获取一页友链评论")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum",value = "页号"),
@ApiImplicitParam(name = "pageSize",value = "每页大小")
}
)
public ResponseResult linkCommentList(Integer pageNum,Integer pageSize){
return
commentService.commentList(SystemConstants.LINK_COMMENT,null,pageNum,pageSize);
}

实体类配置

实体的描述配置 @ApiModel

@ApiModel用于描述实体类。

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description = "添加评论dto")
public class AddCommentDto{
//..
}

实体的属性的描述配置 @ApiModelProperty

@ApiModelProperty用于描述实体的属性

@ApiModelProperty(notes = "评论类型（0代表文章评论，1代表友链评论）")
private String type;

文档信息配置

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zzq.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("张志琪", "http://www.zzq.com",
                "my@my.com");
        return new ApiInfoBuilder()
                .title("ZZQBlog项目")
                .description("用户端相关接口")
                .contact(contact) // 联系方式
                .version("1.1.0") // 版本
                .build();
    }
}

运行，成功！