一. 背景
在前后端分离开发中通常由后端程序员设计接口,完成后需要编写接口文档,最后将文档交给前端工程师,前端工程师参考文档进行开发。
可以通过一些工具快速生成接口文档 。
二. 什么是Swagger?
OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程,目前版本是V3.0,并且已经发布并开源在github上。(链接:GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository)
Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,Swagger是一个在线接口文档的生成工具,前后端开发人员依据接口文档进行开发。 (官网:https://swagger.io/)
Spring Boot 可以集成Swagger,Swaager根据Controller类中的注解生成接口文档 ,只要添加Swagger的依赖和配置信息即可使用它。
三.Swagger的作用
-
Rest API文档的在线自动生成。
-
功能测试。
四.Spring Boot 集成 swagger
准备:
(注:也可以用其他的版本,如果不兼容再考虑下面的版本)
-
JDK1.8
-
SpringBoot2.3.4 + maven3.8.1
1. 在SpringBoot项目下,导入swagger依赖
<!-- Spring Boot 集成 swagger -->
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
<!-- swagger注解的jar包 -->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.20</version>
</dependency>
2.在对应的启动类上添加注解 @EnableSwagger2Doc,启动Swagger
3.配置文件配置Swagger(例如:application.yml,bootstrap.yml等等)
(注:因Swagger采用yml配置文件,所以不再需要编写SwaggerConfig配置类了)
配置如下(这只是一部分):
swagger:
title: "这里是一个title"
description: "这里是一个description"
base-package: com.xuecheng.content #必需,接口包扫描路径
enabled: true
version: 1.0.0
启动对应的服务后,浏览器访问
http://localhost:对应服务的端口号/swagger-ui.html
4.swagger的常用注解
- @Api:用在Controller类上,描述该类的作用。
示例:
@Api(value = "课程信息编辑接口",tags = "课程信息编辑接口")
@RestController //相当于@Controller与@ResponseBody(响应json数据)
public class CourseBaseInfoController {
@Autowired
CourseBaseInfoService courseBaseInfoService;
// @RequestBody(required = false)表示可以为空,它默认为true,不允许为空
@ApiOperation("课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(@ApiParam("分页参数") PageParams pageParams, @RequestBody(required = false) QueryCourseParamsDto queryCourseParamsDto){
PageResult<CourseBase> courseBasePageResult = courseBaseInfoService.queryCourseBaseList(pageParams, queryCourseParamsDto);
return courseBasePageResult;
}
}
-
@ApiOperation:用在方法上,描述该方法的作用。
-
@ApiParam:用在参数上,描述该方法的作用
如:
@ApiOperation("课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(@ApiParam("分页参数") PageParams pageParams, @RequestBody(required = false) QueryCourseParamsDto queryCourseParamsDto){
PageResult<CourseBase> courseBasePageResult = courseBaseInfoService.queryCourseBaseList(pageParams, queryCourseParamsDto);
return courseBasePageResult;
}
-
@ApiModel: 用在模型类上,对模型类作注解
-
@ApiModelProperty:用在成员变量(属性)上,对成员变量作注解
示例:
@Data
@ApiModel(value="TeachplanDto", description="课程计划信息Dto")
public class TeachplanDto extends Teachplan {
@ApiModelProperty(value = "与媒资管理的信息")
private TeachplanMedia teachplanMedia;
@ApiModelProperty(value = "小章节list")
private List<TeachplanDto> teachPlanTreeNodes;
}
5.注解里的属性说明
6.案例演示:
点击第一个方法查看详情,并可以测试:
最下面有模型信息