Swagger快速入门（springBoot集成Swagger）

一. 背景

在前后端分离开发中通常由后端程序员设计接口，完成后需要编写接口文档，最后将文档交给前端工程师，前端工程师参考文档进行开发。

可以通过一些工具快速生成接口文档 。

二. 什么是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.案例演示：

点击第一个方法查看详情，并可以测试：

最下面有模型信息