SpringBoot3使用Springdoc OpenAPI集成接口文档

最新推荐文章于 2024-07-27 15:01:33 发布
最新推荐文章于 2024-07-27 15:01:33 发布
阅读量2.1k 收藏 32
点赞数 47
分类专栏： Java高级 文章标签： java 开发语言
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_51774011/article/details/140396944
版权

步骤1：添加依赖

在pom.xml中添加Springdoc OpenAPI的依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.0</version>
</dependency>

步骤2：基本配置

1. 关于文档信息定制的配置

yaml文件
springdoc:
  api-docs:
    path: /api-docs  # 配置 OpenAPI 文档的路径
  swagger-ui:
    path: /swagger-ui.html  # 配置 Swagger UI 的路径
    enabled: true  # 启用 Swagger UI
    
  # 定制文档基本信息
  info:
    title: API 文档标题  # 设置文档标题
    description: API 文档描述  # 设置文档描述
    version: 1.0.0  # 设置 API 版本
    terms-of-service: https://example.com/terms  # 服务条款 URL
    
    # 关于开发者
    contact:
      name: 开发者姓名  # 开发者联系人姓名
      url: https://example.com/contact  # 联系方式 URL
      email: dev@example.com  # 开发者联系邮箱
      
    # 关于许可证
    license:
      name: Apache 2.0  # 许可证名称
      url: https://www.apache.org/licenses/LICENSE-2.0.html  # 许可证 URL
      
  # 定制服务器基本信息
  servers:
    - url: http://localhost:8080  # 服务器 URL
      description: 本地服务器  # 服务器描述
    - url: https://api.example.com  # 服务器 URL
      description: 生产服务器  # 服务器描述
      
  # 定制外部文档信息
  external-docs:
    description: 外部文档描述  # 外部文档描述
    url: https://example.com/docs  # 外部文档 URL
properties文件
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.enabled=true
springdoc.info.title=API 文档标题
springdoc.info.description=API 文档描述
springdoc.info.version=1.0.0
springdoc.info.terms-of-service=https://example.com/terms
springdoc.info.contact.name=开发者姓名
springdoc.info.contact.url=https://example.com/contact
springdoc.info.contact.email=dev@example.com
springdoc.info.license.name=Apache 2.0
springdoc.info.license.url=https://www.apache.org/licenses/LICENSE-2.0.html
springdoc.servers[0].url=http://localhost:8080
springdoc.servers[0].description=本地服务器
springdoc.servers[1].url=https://api.example.com
springdoc.servers[1].description=生产服务器
springdoc.external-docs.description=外部文档描述
springdoc.external-docs.url=https://example.com/docs

2. 自定义配置类

import org.springdoc.core.customizers.OpenApiCustomizer;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.ExternalDocumentation;
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 io.swagger.v3.oas.models.servers.Server;

@Configuration
public class OpenApiConfig {

    // OpenAPI类用于定制全局文档信息
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            // 定制文档基本信息
            .info(new Info()
                  //关于文档信息
                .title("API 文档标题")
                .description("API 文档描述")
                .version("1.0.0")
                .termsOfService("https://example.com/terms")
                  
                  //关于作者
                .contact(new Contact()
                    .name("开发者姓名")
                    .url("https://example.com/contact")
                    .email("dev@example.com"))
                  
                  //关于许可证
                .license(new License()
                    .name("Apache 2.0")
                    .url("https://www.apache.org/licenses/LICENSE-2.0.html")))
            
            //配置服务器信息
            .servers(List.of(
                new Server().url("http://localhost:8080").description("本地服务器"),
                new Server().url("https://api.example.com").description("生产服务器")))
            
            //配置外部文档信息
            .externalDocs(new ExternalDocumentation()
                .description("外部文档描述")
                .url("https://example.com/docs"));
    }

    // GroupedOpenApi类用于API分组
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/api/**")
            .build();
    }

    // OpenApiCustomizer类用于自定义OpenAPI对象，比如全局添加头部信息。
    @Bean
    public OpenApiCustomizer customerGlobalHeaderOpenApiCustomizer() {
        return openApi -> openApi.info(
            new Info().title("自定义 API 文档")
                .description("自定义 API 文档描述")
                .version("1.0.0")
        );
    }
}
说明
  1. OpenAPI 类：用于设置全局的 API 文档信息，例如标题、描述、版本、联系信息、许可证、服务器和外部文档等。
  2. GroupedOpenApi 类：用于将 API 分组。例如，可以将公共 API 和私有 API 分开。
  3. OpenApiCustomizer 接口：用于自定义 OpenAPI 对象，例如全局添加头部信息等

步骤3：使用注解

Springdoc OpenAPI使用一系列的注解来增强和定制API文档。常用的注解包括@Operation、@Parameter、@Schema等。

在控制器方法上使用注解
import org.springframework.web.bind.annotation.*;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@RestController
@RequestMapping("/api")
public class UserController {

    @Operation(summary = "获取用户信息", description = "根据用户ID获取用户详细信息")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "成功"),
        @ApiResponse(responseCode = "404", description = "用户未找到")
    })
    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        // 实现获取用户的逻辑
        return new User();
    }

    @Operation(summary = "创建新用户", description = "创建一个新的用户")
    @PostMapping("/users")
    public User createUser(@RequestBody CreateUserRequest request) {
        // 实现创建用户的逻辑
        return new User();
    }
}
在实体类上使用注解
import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户ID", example = "1")
    private Long id;

    @Schema(description = "用户名", example = "john_doe")
    private String username;

    @Schema(description = "用户年龄", example = "25")
    private Integer age;

    // getters and setters
}

步骤4：访问在线接口文档

启动Spring Boot应用后，访问http://localhost:8080/swagger-ui.html可以查看生成的API文档界面。

注解详解

1. @Operation

@Operation注解用于描述一个具体的API操作。它可以添加到控制器的方法上，用于定义操作的基本信息。

属性：

  • summary：操作的简要描述。
  • description：操作的详细描述。
  • tags：与操作相关的标签。
  • operationId：操作的唯一标识符。
  • parameters：操作的参数列表。
  • responses：操作的响应列表。

示例：

@Operation(
    summary = "获取用户信息",
    description = "根据用户ID获取用户详细信息",
    tags = {"用户操作"},
    operationId = "getUserById"
)
@RequestMapping("/users")
public User getUserById(@PathVariable Long id) {
    // 实现逻辑
}

2. @Parameter

@Parameter注解用于描述方法参数。它可以添加到控制器方法的参数上。

属性：

  • name：参数名。
  • description：参数描述。
  • required：是否必需参数。
  • in：参数所在位置（query、header、path、cookie）。

示例：

@Operation(summary = "删除用户")
@DeleteMapping("/users/{id}")
public void deleteUser(@Parameter(description = "用户ID", required = true) @PathVariable Long id){
    // 实现逻辑
}

3. @RequestBody

@RequestBody注解用于描述请求体中的内容。它通常添加到方法的参数上，标识该参数是请求体。

属性：

  • description：请求体的描述。
  • required：是否必需。

示例：

@Operation(summary = "创建新用户")
@PostMapping("/users")
public User createUser(@RequestBody(description = "用户创建请求", required = true) CreateUserRequest request)
{
    // 实现逻辑
}

4. @ApiResponse 和 @ApiResponses

@ApiResponse注解用于描述单个API响应，而@ApiResponses注解用于包含多个@ApiResponse注解。

属性：

  • responseCode：响应代码。
  • description：响应描述。
  • content：响应内容。

示例：

@Operation(summary = "获取用户信息")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功获取用户信息"),
    @ApiResponse(responseCode = "404", description = "用户未找到")
})
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    // 实现逻辑
}

5. @Schema

@Schema注解用于描述实体类及其属性。它可以添加到类和属性上。

属性：

  • description：模型或属性的描述。
  • example：示例值。
  • required：必需属性。
  • hidden：是否隐藏属性。

示例：

@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户ID", example = "1")
    private Long id;

    @Schema(description = "用户名", example = "john_doe")
    private String username;

    @Schema(description = "用户年龄", example = "25")
    private Integer age;

    // getters and setters
}

6. @Tag

@Tag注解用于为API操作分组。可以添加到类或方法上。

属性：

  • name：标签名。
  • description：标签描述。

示例：

@Tag(name = "用户操作", description = "与用户相关的操作")
@RestController
@RequestMapping("/api")
public class UserController {
    // 控制器方法
}

7. @Hidden

@Hidden注解用于隐藏API操作、参数或模型属性，不在生成的文档中显示。

示例：

@Hidden
@GetMapping("/hidden")
public void hiddenMethod() {
    // 实现逻辑
}

8. @Content 和 @MediaType

@Content注解用于描述请求或响应的内容，而@MediaType注解用于指定内容类型。

示例：

@Operation(summary = "创建新用户")
@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "用户创建成功",
        		 content = @Content(mediaType = "application/json",
      								schema = @Schema(implementation = User.class)
                 )
              )
})
@PostMapping("/users")
public User createUser(@RequestBody CreateUserRequest request) {
    // 实现逻辑
}
是清醒也是知趣
关注
专栏目录
springboot与springdoc openapi3的整合demo
12-08
springboot与springdoc openapi3的整合demo代码，里面包含swagger3的注解使用说明，还有swagger3的分组配置，以及其他配置说明
springdoc-openapi：具有spring-boot的OpenAPI 3库
01-29
致谢 介绍 springdoc-openapi Java库有助于使用Spring Boot项目自动生成API文档。 springdoc-openapi的工作原理是在运行时检查应用程序以基于Spring配置，类结构和各种注释来推断API语义。 该库会自动以JSON / YAML和HTML格式的页面生成文档。 可以使用swagger-api注释对生成的文档进行补充。 该库支持： OpenAPI 3 Spring启动（v1和v2） JSR-303，专门用于@ NotNull，@ Min，@ Max和@Size。 Swagger-ui Oauth 2 以下视频介绍了库： 这是一个基于社区的项目，不是由Spring Framework Contributors（Pivotal）维护的 入门 用于springdoc-openapi与spring-boot和swagger-ui集成的库 自动将swagger-ui部署到Spring Boot 2.x应用程序 使用官方的 ，将以HTML格式提供文档。 然后，应该在可以找到Swagger UI页面，OpenAPI描述将在json格式的
使用SpringDoc生成接口文档
最新发布
竹林幽深
07-27 170
定义文档标题、文档版本号等信息。description = "UJCMS 接口文档",也可使用Java代码@Beanreturn new OpenAPI().info(new Info().title("UJCMS API").description("UJCMS 接口文档").version("1.0.0"));info:description: UJCMS 接口文档。
SpringBoot集成Swagger，前后端接口文档解决方案。集成SpringDoc，支持SpringBoot3.x。
头好重好重的博客
01-21 3468
一个不断在迭代的项目，Controller层与POJO层肯定会是经常变动的，在目前前后端分离的大环境背景下有一份接口文档可以极大减少项目组成员之间的交流成本，也能支持自动化测试，但靠人工维护该文档总是不够稳妥，因此我们可以使用Swagger或SpringDoc，为响应式接口文档提供了一种解决方案。
Java21 + SpringBoot3整合springdoc-openapi，自动生成在线接口文档，支持SpringSecurity和JWT认证方式
zzcoder的博客
01-31 2605
近日心血来潮想做一个开源项目，目标是做一款可以适配多端、功能完备的模板工程，包含后台管理系统和前台系统，开发者基于此项目进行裁剪和扩展来完成自己的功能开发。本项目为前后端分离开发，后端基于Java21和开发，后端使用JWT等技术栈，前端提供了vueangularreactuniapp微信小程序等多种脚手架工程。本文主要介绍在项目中如何整合实现自动生成在线接口文档，JDK版本是Java21。OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。
SpringBoot3 集成SpringDoc/Swagger、Knife4j
一碗清深的博客
11-17 488
本文将介绍如何使用SpringDoc替代SpringFox，并提供了一些注意事项和示例代码。希望通过本文的介绍，能够帮助大家更好地理解和使用SpringDoc，提升API文档的编写和管理效率。让我们一起开始吧！
Spring Boot 整合 springdoc-openapi
wangzhihao的博客
09-04 2万+
springdoc-openapi使用 springdoc-openapi官网：springdoc.org springdoc-openapi Github仓库：springdoc / springdoc-openapi springdoc-openapi Maven仓库：Home » org.springdoc » springdoc-openapi-ui open api 简介 OpenApi是一个业界的 api 文档标准，一个规范。 好比java里面一个抽象的概念，即是一个抽象类，只是提供了一个api
SpringBoot3整合swagger（springdoc-openapi）
蓝影铁哥的博客
06-01 1万+
SpringBoot3、swagger3、springdoc-openapi、jdk17
聊聊接口文档的事儿
京茶吉鹿的博客
01-01 4242
如何在项目中使用接口文档，接口文档的详细搭建步骤，包含Swagger 与 Knife4j
spring boot3 集成swagger3
不要和代码过不去
07-20 4083
1 设置pom.xml 主要是引入nexus-maven，com.github.xiaoymin 2个，cn.hutool，org.springframework。2随意位置创建 SwaggerConfig。3修改 DemoApplication。4:给控制文件添加对应注解。
Spring Boot 3 整合 SpringDoc OpenAPI 生成接口文档教程配套源码
06-20
该源码对应个人博客【Spring Boot 3整合SpringDoc OpenAPI生成接口文档】配套教程，地址：https://blog.csdn.net/lhmyy521125/article/details/139824967 小伙伴可以自行下载学习！不需要积分！不需要积分！不需要...
springdoc-openapi-demos:带有Spring-boot的OpenAPI 3演示
05-13
OpenAPI 3是Swagger的最新版本，它允许开发者以YAML或JSON格式定义RESTful API，包括接口、参数、响应等细节，生成清晰的交互式文档，便于开发者理解和使用。Springdoc-openapi则是Spring Boot的一个开源库，它为...
springboot-knife4j 实现API文档
09-05
总结，"springboot-knife4j 实现API文档"项目是关于如何在Spring Boot项目中利用Knife4j这一强大的工具，生成专业且易于使用的API文档。通过深入理解并实践这些知识点，开发者可以提升API文档的质量，促进团队间的...
用Spring Doc代替Swagger
热门推荐
吴名氏的博客
04-12 11万+
用Spring Doc代替Swagger
Spring Boot3.x 使用SpringDoc生成接口文档-超级完善 + knife4jUI
BUG制造者的博客
10-17 2325
依赖knife4j jar以上就是今天要讲的内容，本文仅仅简单集成了SpringDoc的使用，有不明白的赶紧下方留言。
Spring Boot 3 整合 SpringDoc OpenAPI 生成接口文档
傲泣龙腾的博客
06-20 1万+
在我们日常开发过程中，维护良好的API文档对于团队协作和开发效率至关重要。是一个强大的工具，能够帮助我们轻松生成规范的文档，并提供交互式的Swagger UI界面。本文跟着博主一起来学习如何在项目中整合，生成在线接口文档目前有两个版本1.x以及2.x, 以下是版本对应的支持：Springdoc OpenAPI 1.x：支持 JDK 8 及以上版本（Spring Boot 2.x and 1.x.）
Springboot3整合OpenAPI(Swagger3)
weixin_59806289的博客
07-15 682
Operation(summary = "用户注册API", description = "用户注册")在Spring Boot项目中创建一个配置类`SwaggerConfig`，并添加Swagger的配置信息。@Tag(name = "用户控制器", description = "用户控制器Controller")@Schema(name = "Employee", description = "员工实体类")首先，您需要在项目的`pom.xml`文件中添加Swagger3的依赖。
Spring Boot: Spring Doc生成OpenAPI3.0文档
liululee的博客
11-25 1万+
1. 概述 公司正好最近在整理项目的文档，且文档对于构建REST API来说是至关重要的。在这篇文章中，我将介绍Spring Doc ， 一个基于OpenAPI 3规范简化了Spring Boot 1.x和2.x应用程序的API文档的生成和维护的工具。 2. 设置springdoc-openapi 如果想让 springdoc-openapi 为我们的API生成标准的 OpenAPI 3 文档, ...
我想springboot3集成springDoc2
07-28
要在Spring Boot 3中集成springdoc 2，你可以按照以下步骤进行操作： 1. 添加依赖项：在你的项目的构建文件（例如 pom.xml）中，添加以下依赖项（请替换版本号为最新版本）： ```xml <dependencies> <!-- Spring Boot Web Starter --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Springdoc OpenAPI --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-core</artifactId> <version>1.5.9</version> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.5.9</version> </dependency> </dependencies> ``` 2. 配置Swagger UI：在你的应用程序配置类上添加 `@EnableOpenApi` 注解，启用Springdoc OpenAPI。 ```java import org.springframework.context.annotation.Configuration; import org.springdoc.api.annotations.EnableOpenApi; @Configuration @EnableOpenApi public class OpenApiConfig { } ``` 3. 在浏览器中访问Swagger UI：启动你的应用程序后，在浏览器中访问 `http://localhost:8080/swagger-ui.html`，你将看到生成的API文档。 请注意，上述步骤是基于Spring Boot 2.x版本的。如果你的项目使用的是Spring Boot 3.x版本，可能需要更新springdoc-openapi-core和springdoc-openapi-ui的版本以适配Spring Boot 3。你可以查看springdoc的官方文档以获取更多信息和最新版本。 希望这能帮助你集成springdoc 2到你的Spring Boot 3项目中，如果你有任何其他问题，请随时提问。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值