【项目学习01_2024.04.27_Day02】

3 课程查询

3.4 生成接口文档

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，Swagger是一个在线接口文档的生成工具，前后端开发人员依据接口文档进行开发。
Swagger

Spring Boot 可以集成Swagger，Swaager根据Controller类中的注解生成接口文档 ，只要添加Swagger的依赖和配置信息即可使用它。

@ApiOperation(“课程查询接口”) 和@Api注解的区别

@ApiOperation("课程查询接口") 和 @Api 注解是 Swagger（一个用于构建、文档化和调用 Web 服务的工具）中的注解，用于描述和配置接口文档信息。
@Api注解用于标注在 Controller 类上，表示对整个控制器的描述信息，比如接口的名称、描述等。
@ApiOperation(“课程查询接口”)注解用于标注在具体的接口方法上，表示对该接口方法的描述信息，比如接口的功能、参数、返回值等。
因此，@Api 注解用于描述整个控制器，而 @ApiOperation 注解用于描述具体的接口方法。通过这两个注解，可以清晰地了解接口的功能和参数信息，方便开发人员和用户查看和理解接口文档。

@Api(value = “课程信息编辑接口”,tags = “课程信息编辑接口”)其中的value和tags有什么用呢

在 Swagger 中，@Api 注解用于描述整个控制器或接口的信息，其中 value 和 tags 是两个重要的属性：

• value: 用于指定接口或控制器的简要描述，通常表示接口或控制器的名称或功能。这个值会显示在 Swagger 文档中，帮助用户快速了解接口或控制器的作用。
• tags: 用于指定接口或控制器所属的标签，可以将相似功能的接口或控制器归类到同一个标签下。在 Swagger 文档中，标签会以分类的形式展示，方便用户按照标签查看相关接口或控制器。
  通过在 @Api 注解中使用 value 和 tags 属性，可以使接口文档更加清晰和易于理解，用户可以快速浏览和查找所需的接口信息。这样可以提高接口文档的可读性和用户体验。

Swaager的常用注解如下：

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

3.5 开发持久层

3.5.1 生成mapper

本项目使用MyBatis-Plus开发持久层，需要创建PO类、Mapper接口、Mapper的xml文件，每个PO类对应数据库的每张表，每张表需要创建一个Mapper接口和Mapper的xml映射文件 。
下边将使用generator工程生成的mapper接口和mapper映射文件 拷贝到service工程 。
service工程即业务层为api接口工程提供业务处理支撑，本项目业务层包括了持久层的代码，一些大型公司的团队职责划分更细，会将持久层和业务层分为两个工程，不过这需要增加成本。

3.5.2 测试mapper

下边对mapper进行单元测试，测试course_base表的查询接口。
1、下边在service工程的pom.xml中添加依赖

<dependencies>
    <dependency>
        <groupId>com.xuecheng</groupId>
        <artifactId>xuecheng-plus-content-model</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>

    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>

    <!-- mybatis plus的依赖 -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
    </dependency>
   <dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-context</artifactId>
  </dependency>
    <!-- Spring Boot 集成 Junit -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <!-- 排除 Spring Boot 依赖的日志包冲突 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
        <exclusions>
            <exclusion>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>

    <!-- Spring Boot 集成 log4j2 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-log4j2</artifactId>
    </dependency>

</dependencies>

这两个依赖的作用主要是为了解决日志相关的问题，并提供更好的日志管理和记录功能：

1. 排除默认日志包依赖的好处：Spring Boot 默认使用 Logback 作为日志框架，但有时候我们可能更喜欢使用其他日志框架，比如 Log4j2。通过排除默认的日志包依赖，我们可以避免引入不需要的日志框架，减少项目中的依赖冲突和混乱。

2. 集成 Log4j2 的好处：Log4j2 是一个功能强大、配置灵活的日志框架，可以帮助我们更好地记录应用程序的日志信息。通过集成 Log4j2 到 Spring Boot 项目中，我们可以使用 Log4j2 提供的丰富功能，比如灵活的日志级别控制、日志文件分割、日志格式定制等，从而更好地管理和监控应用程序的日志输出。

综合来说，通过这两个依赖的配置，我们可以灵活选择和配置适合项目需求的日志框架，提高日志记录的灵活性和可维护性，同时避免日志包冲突和混乱，让日志管理变得更加方便和有效。

3、配置扫描mapper及分页插件
分页插件的原理：
首先分页参数放到ThreadLocal中，拦截执行的sql，根据数据库类型添加对应的分页语句重写sql，例如：(select * from table where a) 转换为 (select count(*) from table where a)和(select * from table where a limit ,)
计算出了total总条数、pageNum当前第几页、pageSize每页大小和当前页的数据，是否为首页，是否为尾页，总页数等。

4、单元测试所需要的配置文件
在test/resources下创建 log4j2-dev.xml、bootstrap.yml

5、编写启动类：
单元测试工作在test目录，在test下添加启动类

6、编写测试类