【springboot系列】springboot3集成springdoc

SpringDoc介绍

简介

SpringDoc OpenAPI 是一个用于Spring Boot和Spring MVC应用程序的API文档生成器，它基于OpenAPI 3标准。

SpringDoc自动从你的Spring应用中提取元数据来生成详细的API文档，无需额外的手动编写文档工作。

它支持自动识别Spring MVC控制器和Spring WebFlux路由器功能，并能很好地集成Swagger UI和ReDoc等界面，以便开发者和用户能够直观地浏览和测试API。

主要特点包括：

• 自动化处理： 自动扫描和解析控制器类和方法，减少手动维护文档的工作量。
• OpenAPI 3支持： 生成符合OpenAPI 3规范的文档，该规范是REST API设计和文档的最新行业标准
• 易集成： 零配置启动，只需引入依赖即可开始使用。
• UI支持： 内置对Swagger UI、ReDoc的支持，便于查看和测试API。
• 扩展性： 支持自定义和扩展文档内容，如添加安全需求、自定义响应等。

与Swagger对比

对比项	swagger2	spirngdoc
依赖和更新	配置和依赖较多	依赖少，配置简洁，易于集成
标准支持	支持openapi2.0规范	面向openapi3.0
自动化程度	需要更多的注解来细化文档信息	自动发现和生成API文档
性能	高	略高于swagger
社区和生态	社区生态丰富，有很多插件和工具	完善过程中

简单集成

目录结构

新建springboot+maven项目

引入pom依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>springdoc-demo</artifactId>
    <version>1.0-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.2</version>
    </parent>

    <properties>
        <maven.compiler.source>20</maven.compiler.source>
        <maven.compiler.target>20</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
    </dependencies>
</project>

添加controller

package com.zjtx.tech.springdoc.controller;

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("demo")
public class DemoController {

    @Operation(summary = "测试")
    @GetMapping("d")
    public String demo() {
        return "demo";
    }

}

package com.zjtx.tech.springdoc.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "公共接口")
@RestController
@RequestMapping("/public")
public class PublicController {

    @Operation(summary = "hello")
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }
}

本地测试

访问本地默认swagger地址: http://localhost:8080/swagger-ui/index.html 来测试。

效果如下图:

经过以上步骤我们就完成了springdoc的简单集成，非常简单。

接下来我们实验以下spingdoc中提供的一些个性化配置，比如想加入公司或者产品的基本信息，比如想实现api的分组，比如需要在线上关闭swagger文档等。

springdoc配置说明

基本信息配置

添加配置类SpringDocConfig.java， 可以配置标题、描述、联系人等信息。

package com.zjtx.tech.springdoc.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("演示文档标题")
                        .description("演示文档描述")
                        .version("1.0.0")
                        .contact(new Contact()
                                .name("泽济天下")
                                .url("https://www.zjtx.vip")
                                .email("1654088754@qq.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("http://springdoc.org")));
    }
}

分组配置

现在的服务多以微服务架构为主，就会有按微服务展示swagger文档的需求，springdoc也提供了这样的配置。

配置可以通过配置类或者配置文件的方式实现，下面给出示例:

// 如果需要分组API，可以添加如下配置
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .packagesToScan("com.zjtx.tech.springdoc")
                .group("public")
                .pathsToMatch("/public/**")
                .build();
    }

    @Bean
    public GroupedOpenApi demoApi() {
        return GroupedOpenApi.builder()
                .packagesToScan("com.zjtx.tech.springdoc")
                .group("demo")
                .pathsToMatch("/demo/**")
                .build();
    }

以上配置实现了将文档分组为demo和public, 分别对应路径/public/**和``/demo/**`

以下yml配置文件可以实现相同效果:

springdoc:
  group-configs:
    - group: "demo"
      paths-to-match:
        - /demo/**
    - group: "public"
      paths-to-match:
        - /public/**
  packages-to-scan: com.zjtx.tech.springdoc

开关配置

在生产环境部署服务的时候是需要关闭swagger文档的，我们可以通过下面的配置实现:

springdoc:
  enable-data-rest: true
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    show-extensions: true

springdoc常用注解

介绍完了集成和一些配置类，接下来我们来看下springdoc提供的一些常用注解及其使用。

注解介绍

• @Tag：用于标记API控制器或方法属于哪一个功能分类或标签，有助于组织和分类API文档中的不同部分。

  使用位置

• @Operation：用于方法级别，提供对API操作的详细描述，包括摘要、描述、响应、参数等信息。

• @Schema：用于描述类或字段的数据结构和属性，支持OpenAPI 3规范中的各种特性，如类型、格式、默认值等。

• @Parameters是一个容器注解，用于收集多个@Parameter注解，描述方法的多个请求参数。

• @Parameter：用于描述单个请求参数，可以是查询参数、路径参数、请求头等。

• @ApiResponses是一个容器注解，用于收集多个@ApiResponse，描述方法可能返回的各种响应情况。

• @ApiResponse描述了API操作的一个特定响应，包括响应的状态码、描述、内容类型等。

接下来我们通过一个实例展示以上注解的使用。

注解使用

1. 定义一些实体类和DTO

   package com.zjtx.tech.springdoc.dto;
   
   import io.swagger.v3.oas.annotations.media.Schema;
   
   @Schema(description = "用户查询DTO")
   public class UserPageQueryDto {
   
       @Schema(description = "用户名")
       private String username;
   
       @Schema(description = "页码")
       private Integer pageNum;
   
       @Schema(description = "每页数量")
       private Integer pageSize;
   
       //...省略getter和setter
   }
   
   

2. controller中使用注解

   package com.zjtx.tech.springdoc.controller;
   
   import com.zjtx.tech.springdoc.dto.UserPageQueryDto;
   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.Parameter;
   import io.swagger.v3.oas.annotations.media.Content;
   import io.swagger.v3.oas.annotations.media.Schema;
   import io.swagger.v3.oas.annotations.responses.ApiResponse;
   import io.swagger.v3.oas.annotations.tags.Tag;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @Tag(name = "用户接口", description = "用户接口")
   @RestController
   @RequestMapping("user")
   public class UserDemoController {
   
       @GetMapping("query")
       @Parameter(content = @Content(schema = @Schema(implementation = UserPageQueryDto.class)))
       @Operation(summary = "用户分页查询", description = "用户分页查询",
               responses =
                       {@ApiResponse(responseCode = "200", description = "成功", content = @Content(schema = @Schema(implementation = String.class))),
                       @ApiResponse(responseCode = "401", description = "用户未登录")})
       public String getUserPage(UserPageQueryDto dto){
           System.out.println("dto = " + dto);
           return "query";
       }
   
   }
   

测试截图

以上配置完成后访问本地地址效果如下:

springdoc切换ui

pom.xml修改

添加如下jar:

<!--基于knife4j-openapi3的api接口文档生成-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

注意: 本文的springboot版本使用的是3.2.2， jdk版本使用的是20，这里需要使用openapi3的版本。

添加knife4j配置

application.yml文件中添加如下配置:

knife4j:
  enable: true    #开启knife4j，无需添加@EnableKnife4j注解
  setting:
    language: zh_cn   #中文
    swagger-model-name: 实体类   #重命名SwaggerModel名称,默认

验证

浏览器访问http://localhost:8080/doc.html

文档导出

knife4j中提供了文档导出的功能，支持html、markdown、doc等格式。

总结

本文简单介绍了springdoc的使用以及与springboot的集成和配置，同时提供了knife4j的集成和文档导出相关操作。

作为记录的同时也希望能帮助到需要的人，有任何疑问欢迎留言。
创作不易，欢迎一键三连~~