简介
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();
}
}