当前位置： 代码网 > it编程>编程语言>Java > SpringBoot3整合SpringDoc OpenAPI生成接口文档的详细过程

SpringBoot3整合SpringDoc OpenAPI生成接口文档的详细过程

2024年07月19日 • Java •我要评论
1、前言在我们日常开发过程中，维护良好的 api 文档对于团队协作和开发效率至关重要。springdoc openapi 是一个强大的工具，能够帮助我们轻松生成 openapi 3.0 规范的文档，并

1、前言

在我们日常开发过程中，维护良好的 api 文档对于团队协作和开发效率至关重要。springdoc openapi 是一个强大的工具，能够帮助我们轻松生成 openapi 3.0 规范的文档，并提供交互式的 swagger ui 界面。

本文跟着博主一起来学习如何在 spring boot 3 项目中整合 springdoc openapi，生成在线接口文档

2、springdoc openapi版本介绍

目前 springdoc openapi 有两个版本 1.x 以及 2.x , 以下是版本对应的支持：

springdoc openapi 1.x：支持 jdk 8 及以上版本（spring boot 2.x and 1.x.）
springdoc openapi 2.x：最新版本要求 jdk 11 及以上（spring boot 3.x）

下表描述了两个版本主要模块的更改：

springdoc-openapi-v1springdoc-openapi-v2描述
springdoc-openapi-commonspringdoc-openapi-starter-common包含基础springdoc-openapi功能
springdoc-openapi-data-restspringdoc-openapi-starter-commonspringdata rest 支持
springdoc-openapi-groovyspringdoc-openapi-starter-commongroovy支持
springdoc-openapi-hateoasspringdoc-openapi-starter-commonspring hateoas 支持
springdoc-openapi-javadocspringdoc-openapi-starter-commonjavadoc支持
springdoc-openapi-kotlinspringdoc-openapi-starter-commonkotlin支持
springdoc-openapi-securityspringdoc-openapi-starter-commonspring security支持
springdoc-openapi-webmvc-corespringdoc-openapi-starter-webmvc-apispring webmvc支持
springdoc-openapi-webflux-corespringdoc-openapi-starter-webflux-apispring webflux支持
springdoc-openapi-uispringdoc-openapi-starter-webmvc-ui在spring webmvc上下文中使用swagger-ui
springdoc-openapi-webflux-uispringdoc-openapi-starter-webflux-ui在spring webflux上下文中使用swagger-ui

确保你使用的 jdk 版本与 springdoc-openapi 的版本相匹配。如果你使用的是 spring boot 3，springdoc openapi 2.x 是推荐的版本，因为 spring boot 3 也要求 jdk 17 及以上

3、项目初始化

配置依赖

创建一个新的 spring boot 3 项目，这里博主选用的jdk版本为jdk17 ，spring boot: 3.0.0，在我们的在 pom.xml 文件中添加 springdoc openapi 的依赖

	<dependency>
        <groupid>org.springframework.boot</groupid>
        <artifactid>spring-boot-starter-web</artifactid>
    </dependency>
    <!-- springdoc openapi starter -->
   <dependency>
      <groupid>org.springdoc</groupid>
      <artifactid>springdoc-openapi-starter-webmvc-ui</artifactid>
      <version>2.5.0</version>
   </dependency>

配置 springdoc openapi

springdoc-openapi 通过自动配置大多数情况下无需额外配置，但如果小伙伴有特定需求，可以在 application.yml 文件中添加配置，如：

springdoc:
  api-docs:
    enabled: true #
    path: /api-docs # 默认/v3/api-docs
  swagger-ui:
    path: /swagger-ui.html #自定义swagger-ui html文档路径

编写 rest controller

创建一个简单的 rest 控制器，并使用 openapi 注解来描述 api

定义user对象

首先，我们为 user 类的字段添加注解说明

/**
* description 字段描述
* example 字段返回示例
**/
@data
public class user {
    @schema(description = "用户id", example = "1")
    private long id;
    @schema(description = "用户姓名", example = "张三")
    private string name;
    @schema(description = "用户邮箱", example = "zhansan@qq.com")
    private string email;
}

创建一个简单的 rest controller，并使用 openapi 注解来描述 api

import com.toher.springdoc.bean.user;
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.responses.apiresponses;
import org.springframework.web.bind.annotation.*;

/**
 * @author 麦可乐
 * @date 2024/6/20 11:17 am
 * @version 1.0
 */

@restcontroller
@requestmapping("/api/users")
public class usercontroller {

    @operation(summary = "获取用户信息接口", description = "通过用户id获取用户信息")
    @apiresponses(value = {
            @apiresponse(responsecode = "200", description = "用户信息",
                    content = {@content(mediatype = "application/json",
                    schema = @schema(implementation = user.class))}),
            @apiresponse(responsecode = "404", description = "无法获取用户信息")
    })
    @getmapping("/{id}")
    public user getuserbyid(@parameter(description = "用户id") @pathvariable long id) {
        //模拟数据库获取用户
        user user = new user();
        user.setid(1l);
        user.setname("张三");
        user.setemail("zhansan@qq.com");
        return user;
    }

    @operation(summary = "创建用户接口", description = "创建一个新用户并返回带有用户id的user对象")
    @apiresponses(value = {
            @apiresponse(responsecode = "200", description = "用户创建",
                    content = {@content(mediatype = "application/json",
                    schema = @schema(implementation = user.class))})
    })
    @postmapping
    public user createuser(@requestbody user user) {
        //模拟数据库保存用户并返回用户id主键
        user.setid(1l);
        return user;
    }
}

测试查看文档

最后启动项目访问查看文档 http://localhost:端口号/swagger-ui，小伙伴应该能够看到自动生成的 api 文档，并可以在界面中进行 api 测试，如下图：

在这里插入图片描述

4、如何进行文档分组

很多时候我们的接口很多，且可能不同的开发人员分配不同的模块，如果所有接口都集中在一起，很明显不利于我们查阅，这里博主介绍一下如何对文档进行分组。

需要实用一个配置 group-configs， 如博主的配置

springdoc:
  api-docs:
    enabled: true #
    path: /api-docs # 默认/v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
  group-configs: #进行文档分组每个组配置对应的请求路径以及区分所在包
    - group: 'user'
      paths-to-match: '/api/users/**'
      packages-to-scan: com.toher.springdoc.user
    - group: 'product'
      paths-to-match: '/api/product/**'
      packages-to-scan: com.toher.springdoc.product

继续测试访问文档，右上角 select a definition 查看是否已经分组

在这里插入图片描述

5、更换接口文档ui

相信很多小伙伴还是不喜欢swagger-ui的文档，这里博主介绍一个集 swagger2 和 openapi3 为一体的增强解决方案 - knife4j

要使用 knife4j 非常简单，只需要引入依赖即可

<dependency>
    <groupid>com.github.xiaoymin</groupid>
    <artifactid>knife4j-openapi3-jakarta-spring-boot-starter</artifactid>
    <version>4.4.0</version>
</dependency>

如果你希望开启 knife4j 的增强，可以在yml配置文件中追加，具体knife4j增强配置明细，可以查看官方文档 https://doc.xiaominfo.com/docs/features/enhance 这里就不赘述了

# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

重启我们的 springboot 应用访问 http://localhost:端口号/doc.html 查看

在这里插入图片描述

6、字段必填如何设置

相信很多小伙伴在springboot2的时候对于文档中一些字段的要求，如：必填，我们可以使用一个注解属性 required = true 来说明

	@schema(description = "用户姓名", example = "张三" , required = true)
    private string name;

但实际上在最新版本的 springdoc openapi 中，@schema 注解的 required 属性已经被标记为过时。取而代之的是将字段的非空校验放在参数或方法级别的注解上，结合 jakarta.validation

在 springdoc openapi 3 中，你可以使用 @parameter 和 @requestbody 注解来指定字段是否必需，同时在 @schema 注解中可以通过指定非空属性

下面我们来改造一下我们之前的代码

user对象

import io.swagger.v3.oas.annotations.media.schema;
import jakarta.validation.constraints.email;
import jakarta.validation.constraints.notnull;
import lombok.data;

@data
public class user {
    @schema(description = "用户id", example = "1")
    private long id;

    @schema(description = "用户姓名", example = "张三")
    @notnull(message = "name必填")
    private string name;

    @schema(description = "用户邮箱", example = "zhansan@qq.com")
    @notnull(message = "email必填")
    @email(message = "邮箱格式不正确")
    private string email;
}

usercontroller

import com.toher.springdoc.user.bean.user;
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.responses.apiresponses;
import io.swagger.v3.oas.annotations.tags.tag;
import jakarta.validation.valid;
import org.springframework.web.bind.annotation.*;

@restcontroller
@requestmapping("/api/users")
@tag(name = "用户接口")
public class usercontroller {

    @operation(summary = "获取用户信息接口", description = "通过用户id获取用户信息")
    @apiresponses(value = {
            @apiresponse(responsecode = "200", description = "用户信息",
                    content = {@content(mediatype = "application/json",
                    schema = @schema(implementation = user.class))}),
            @apiresponse(responsecode = "404", description = "无法获取用户信息")
    })
    @getmapping("/{id}")
    public user getuserbyid(@parameter(description = "用户id") @pathvariable long id) {
        //模拟数据库获取用户
        user user = new user();
        user.setid(1l);
        user.setname("张三");
        user.setemail("zhansan@qq.com");
        return user;
    }

    @operation(summary = "创建用户接口", description = "创建一个新用户并返回带有用户id的user对象")
    @apiresponses(value = {
            @apiresponse(responsecode = "200", description = "用户创建",
                    content = {@content(mediatype = "application/json",
                    schema = @schema(implementation = user.class))})
    })
    @postmapping
    public user createuser(@valid @requestbody user user) {
        //模拟数据库保存用户并返回用户id主键
        user.setid(1l);
        return user;
    }
}

ok，我们还是重启应用观察文档说明。是否必填项上已经显示必填

在这里插入图片描述

7、结语

通过整合 spring boot 3 和 springdoc openapi，可以非常方便地生成交互式的在线 api 文档，帮助开发者和使用者理解和测试 api。这不仅提高了开发效率，还能保证文档的及时更新，保持与实际代码的一致性。

以上就是springboot3整合springdoc openapi生成接口文档的详细过程的详细内容，更多关于springboot3整合springdoc openapi的资料请关注代码网其它相关文章！

赞 (0)

相关文章:

版权声明：本文内容由互联网用户贡献，该文观点仅代表作者本人。本站仅提供信息存储服务，不拥有所有权，不承担相关法律责任。 如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 2386932994@qq.com 举报，一经查实将立刻删除。

发表评论

验证码：
最近更新的文章
推荐阅读
大家感兴趣的文章
Copyright © 2017-2025  代码网 保留所有权利. 粤ICP备2024248653号
站长QQ:2386932994 | 联系邮箱：2386932994@qq.com