目录
1.Swagger介绍
2.SpringBoot中快速使用Swagger
3.Swagger配置
4.Swagger通过注解描述文档
1.Swagger介绍
Swagger诞生的背景:
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。再次条件下,Swagger就孕育而生了😄。
Swagger官网地址:https://swagger.io/ 。
Swagger简介:
- Swagger号称世界上最流行的Api框架;
- Swagger是Restful Api 文档在线自动生成工具,Api文档与Api定义同步更新;
- 支持在线测试Api接口,相当于自带了一个postman工具;
- 支持多种语言。
2.SpringBoot中快速使用Swagger
导入依赖:
<!-- Swagger-->
<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>
初步简单配置Swager:
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
这样简单配置后就可以是使用Swagger了,访问Swagger提供的UI界面http://localhost:8081/swagger-ui.html ,地址为:项目ip:端口号/swagger-ui.html
。可以看到在UI界面显示了文档基础信息、控制器、控制器下对应的Api信息,实体类等信息。点击Api还可以进行在线请求测试。
3.Swagger配置
Swagger的配置相对来说也比较简单,我们只需要配置一个Swagger的Docket
实例即可。
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(Environment environment) {
//判断当前环境同允许的环境是否匹配
boolean enableSwagger = environment.acceptsProfiles(Profiles.of("dev","test"));
//返回Docket实例
return new Docket(DocumentationType.SWAGGER_2)
//Api组名,我开发的是User模块,则可命名为UserApi;其他人开发的其他模块则以其他的组名配置新的Docket
.groupName("UserApi")
//是否使用Swagger,应该在开发环境使用,生产环境时不使用
.enable(enableSwagger)
//Api的Base路径,所有Api的前缀
.pathMapping("/")
//配置Api文档信息
.apiInfo(apiInfo())
.select()
//配置要扫描的Api:controller包下的所有Api
.apis(RequestHandlerSelectors.basePackage("cn.korb1n.springbootproject.controller"))
//配置要扫描的路径:所有路径
.paths(PathSelectors.any())
.build();
}
public ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Korbin的Api文档")
.description("这是这个Api文档的描述")
.version("文档版本1.0")
.termsOfServiceUrl("http://www.baidu.com?wd=服务条款网址")
.contact(new Contact("Korbin","http://www.korbin.top","86744316@qq.com"))
.license("商标品牌")
.licenseUrl("http://www.baidu.com?wd=品牌官网")
.extensions(new ArrayList<>()).build();
}
}
在这个Docket的Bean中,配置了Swagger要映射路径、要扫描的接口的位置和要使用Swagger的环境;在apiInfo中,主要配置了一下Swagger2文档UI界面网站的信息,如网站的title,网站的描述,联系人的信息,使用的协议等等。
4.Swagger通过注解描述文档
配置好Swagger后,分类生成了Api接口,乍一看上去这个Api文档基本成型,但还缺少了对接口和实体类等的描述和注释,不然开发人员单看着这些接口,也很难知道接口的功能。
在Swagger中我们可以通过其提供的注解,非常便捷的给需要的地方加上描述,详细注解如下表:
注解 | 说明 | 参数 |
---|---|---|
@Api | 作用于类,表示这个类是个Controller控制器 | value:类描述; tags:同样表示描述,但是值为数组 |
@ApiOperation | 作用于方法,表示一个http请求的操作 | value:方法描述;notes:内容提示;tags:可以重新分组(视情况而用) |
@ApiParam | http请求方法的参数,字段说明;表示对参数添加元数据 | name:参数名;value:参数说明;required:是否必填 |
@ApiModel | 作用于类,表示这是一个实体类 | value:实体类对象名;description:描述 |
@ApiModelProperty | 用于方法、字段; 表示对model属性的说明或操作说明 | value:字段说明;name:重写属性名字;dataType:重写属性类型;required:是否必须填写;example:举例说明;hidden:隐藏 |
@ApiIgnore | 用于类或者方法上,可以不被swagger显示在页面上 | 无 |
@ApiImplicitParam | 用于方法(表示单个参数) | name:参数名;value:参数说明;dataType:数据类型;paramType:参数类型;example:举例说明 |
@ApiImplicitParams | 用于方法(表示多个参数),包含多个 @ApiImplicitParam | @ApiImplicitParam |
示例:
@ApiModel(value = "User",description = "用户信息实体类")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
@ApiModelProperty(value = "用户id",example = "100000")
@TableId(type = IdType.AUTO)
private Long id;
}
@Api(tags = "用户控制器")
@RestController
public class UserController {
@Autowired
private UserMapper userMapper;
@ApiOperation(value = "按照id查找用户")
@GetMapping("/user")
public User findById(@ApiParam(name = "id",value = "用户id") Long id){
return userMapper.selectById(id);
}
}
可以看到Api文档的描述信息发生改变了:
注意:如果例如上述的id
字段为Long
,但是在注解中没有写明example
参数,会默认id
的值为空字符串
,就会报错: