SpringBoot集成MybatisPlus-Swagger

SpringBoot集成MybatisPlus-Swagger

一.Swagger介绍

1.介绍：

​ Swagger是一个开源的框架，提供了一组工具，用于设计、构建、记录和使用RESTful API。它可以帮助开发者快速创建API文档，并提供可交互的API控制台，方便前后端协作、测试和调试。

2.swagger的作用：

• 接口文档自动在线生成
• 功能测试

3.swagger的优点：

• ​ 接口文档在线生成，避免同步的麻烦

• ​ 可以支持在线对接口执行测试

4.主要依赖介绍：

• Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、 Swagger 1.2文档转换成 Swagger 2.0文档等功能
• Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成
• Swagger-js: 用于JavaScript的Swagger实现 Swagger-node-express:
• Swagger模块，用于node.js的Expressweb应用框架
• Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文
• Swagger-codegen：模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码

5.主要功能介绍：

• API文档自动生成：通过注解方式描述API接口以及参数，Swagger可以自动生成 API文档，并支持在线预览。
• API控制台：Swagger提供了可交互的API控制台，可以直接在浏览器中测试和 调试API接口。
• API测试：Swagger可以生成可重用的API测试代码，方便开发者进行API测试。
• API监控：Swagger可以监控API的使用情况，包括请求次数、响应时间等统计数据。

二.Swagger使用

1.SpringBoot整合Swagger步骤：

1.1添加Swagger依赖：

<dependency>   
<groupId>io.springfox</groupId>   
<artifactId>springfox-boot-starter</artifactId> 
   <version>3.0.0</version> 
</dependency>

1.2配置Swagger：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 为api选择启动生成器
                .select()
                // 指定要生成api文档的根包
                .apis(RequestHandlerSelectors.basePackage("com.cqgcxy.controller"))
                // 路径配置
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建一个ApiInfo对象
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("农牧慧智慧养殖系统接口")
                // 简介
                .description("案例")
                // 作者信息：作者姓名、作者地址、作者邮箱
                .contact(new Contact("Pep7Chiao", "http://www.baidu.com", "362142370@qq.com"))
                // 版本号
                .version("1.0")
                .build();
    }
}

1.3添加API接口注解:

• @Api：用于描述整个API资源，包括标签、说明等信息。可以标注在Controller类上。

• @ApiOperation：用于描述一个操作（即一个接口），包括方法的作用、说明等信息。可以标注在Controller的方法上。

• @ApiParam：用于描述一个参数，包括参数名、说明、是否必需等信息。可以标注在Controller的方法参数上。

• @ApiModel：用于描述一个返回结果的模型，包括模型的属性、说明等信息。可以标注在返回结果的对象类上。

• @ApiResponse：用于描述一个操作的响应，包括响应码、说明等信息。可以标注在@ApiOperation注解内，用于描述不同的响应情况。

• @ApiResponses：用于包裹多个@ApiResponse注解，用于描述一个操作可能的多种响应情况。

• @ApiImplicitParam：用于描述一个单独的请求参数，包括参数名、参数位置、说明等信息。可以标注在@ApiOperation注解内，用于描述请求参数。

• @ApiImplicitParams：用于包裹多个@ApiImplicitParam注解，用于描述一个操作可能的多个请求参数。

  1.4.添加API接口注解：在Controller类或方法上使用Swagger的注解描述API接口和参数:

  @RestController
  @RequestMapping("/api")
  @Api(tags = "示例API") 
  public class SampleController {     @GetMapping("/hello")    
  @ApiOperation("示例接口")   
  public String sayHello(@RequestParam String name) {    
      return "Hello, " + name + "!";    } }
  
  
  

  1.5启动应用程序：运行你的Spring Boot应用程序

  1.6访问Swagger UI：在浏览器中访问http://localhost:port/swagger-ui.html，其中port是端口号,有自动生成的API文档页面，可以在其中查看和测试API接口
  

三.Swagger异常报错和解决方案

1. 无法访问Swagger UI页面:

当访问http://localhost:port/swagger-ui.html时，可能会提示页面不存在或者无法连接等错误。这种情况一般是因为Swagger的配置有误，可以检查以下几项：

• 是否正确引入了Swagger的依赖。
• 是否正确配置了Swagger的启动类，包括@EnableSwagger2注解、@Configuration注解等。
• 是否在Controller类和方法上正确使用了Swagger的注解，例如@Api、@ApiOperation、@ApiParam等。

2. API文档中无法展示接口信息:

当访问Swagger UI页面时，可能会看到API文档中没有展示接口的信息，或者只展示了部分接口。这种情况一般是因为Swagger的扫描配置不正确，可以检查以下几项：

• 是否在启动类中配置了正确的扫描路径，包括Controller类所在的包路径等。
• 是否在Swagger的配置类中开启了扫描功能，例如使用了@EnableSwagger2注解。

3. Swagger请求测试时出现错误:

当在Swagger UI页面进行接口测试时，可能会出现请求失败、请求超时等错误。这种情况一般是因为接口本身存在问题，或者接口所依赖的服务不可用。可以检查以下几项：

• 检查接口的参数是否正确，是否缺少必需的参数等。
• 检查接口所依赖的服务是否正常运行，例如数据库是否能够连接、接口依赖的服务是否可用等。
• 检查接口的代码实现是否正确，是否存在逻辑错误等。

4. Swagger与Spring Security集成时出现问题:

当在Spring Boot应用中使用Spring Security进行安全控制时，可能会出现无法访问Swagger UI页面、无法测试API接口等问题。这种情况一般是因为Swagger的配置与Spring Security的配置冲突，可以尝试以下几种解决方案：

• 配置Spring Security，允许Swagger UI页面和API接口的访问

• 在Swagger的配置类中排除Spring Security的路径，避免冲突

• 使用Springfox的Spring Security支持插件，解决冲突问题

5.SpringBoot 与 Swagger23版本冲突问题（重点）：

       5.1SpringBoot 与 Swagger 版本冲突原因：

• 版本不匹配：不同版本的Spring Boot和Swagger2可能依赖于不同版本的相关库。如果使用的Spring Boot版本与Swagger2所需的依赖库版本不兼容，可能会导致冲突。在集成Swagger2时，应确保选择与SpringBoot版本兼容的Swagger2版本。

• 重复的依赖：项目中可能存在多个相同的依赖项，但版本不同。这可能导致冲突，特别是如果这些依赖项同时被Spring Boot和Swagger2所使用。解决方法是检查项目的依赖项，并确保只包含必要的依赖项，避免重复引入。

• 配置冲突：Spring
  Boot和Swagger2可能有一些共同的配置属性，如果配置不正确，也可能导致冲突。例如，如果两者都尝试配置应用程序的上下文路径或端口号，则可能发生冲突。在集成时，应确保正确配置Spring
  Boot和Swagger2的相关属性，避免冲突。
  5.2解决方案：

  • 将启动类中的@EnableSwagger2替换为@EnableSwagger2WebMvc

  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  // 为api选择启动生成器
                  .select()
                  // 指定要生成api文档的根包
                  .apis(RequestHandlerSelectors.basePackage("com.cqgcxy.controller"))
                  // 路径配置
                  .paths(PathSelectors.any())
                  .build();
      }
  

• 启动类

  @SpringBootApplication
  //@MapperScan
  @EnableSwagger2
  public class App {
      public static void main(String[] args) {
  //        传参(里面内嵌tomcat)
          SpringApplication.run(App.class,args);
      }
  }
  

四.总结

​ 1.MybatisPlus可以简化Mybatis的使用，提高开发效率，Swagger则可以自动生成API文档，方便前后端协作开发。集成MybatisPlus需要在pom.xml文件中添加相应的依赖，然后在配置文件中进行数据源、Mybatis、MybatisPlus等相关配置。同时，还需要创建实体类、Mapper接口等相关文件，并使用MybatisPlus提供的注解进行映射配置，通过集成MybatisPlus和Swagger，可以大幅度提高项目开发效率和可维护性，同时也能为团队协作开发提供极大的便利。

2.集成Swagger也需要在pom.xml文件中添加相应的依赖，在启动类中使用@EnableSwagger2（或@EnableSwagger2WebMvc）注解来启用Swagger的支持，还需要创建Swagger的配置类，并进行相应的API信息、扫描包路径等配置。

3.集成MybatisPlus和Swagger的步骤较为类似，都需要添加依赖、进行配置，并编写相关的代码和注解。其中需要注意的是，不同版本的MybatisPlus和Swagger之间可能存在不兼容的情况，因此需要确保版本的兼容性。