Spring_Boot整合Swagger教程详解

# 什么是Swagger

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。它可以轻松的整合到现有的项目中，生成文档提供给前端开发人员来调用，还可以做功能测试。在 Spring Boot 中，我们可以通过集成 Swagger 来实现接口文档的自动生成。Swagger 通过注解来描述接口，然后根据这些注解自动生成接口文档。

# 什么是Springdoc-openapi

SpringBoot官宣推出API工具官网地址 https://springdoc.org/#getting-started
支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目

# 什么是openapi

OpenAPI Specification（OAS）定义了一个标准，用于描述REST API。它具有与Swagger 2.0规范兼容的根基础，但具有更强大的功能，例如支持JSON和YAML序列化，更好的安全性等。 [了解OpenAPI：什么是OpenAPI及其作用] https://zhuanlan.zhihu.com/p/624773325

# Springdoc-openapi 与 Swagger的区别

Springdoc-openapi是SpringBoot官方推出的API工具，支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目。 Springdoc-openapi是基于OpenAPI 3规范构建的，而Swagger是基于OpenAPI 2规范构建的。

Springdoc-openapi 能代替 Swagger么答案是可以的,但是Springdoc-openapi是基于OpenAPI 3规范构建的，而Swagger是基于OpenAPI 2规范构建的，所以在使用Springdoc-openapi时，需要注意一些细节，比如注解的变化等。

# Springdoc-openapi的使用

# 引入依赖

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

1
2
3
4
5

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

1
2

# 启动项目

访问 http://localhost:8080/swagger-ui.html

访问 http://localhost:8080/v3/api-docs 可以查看接口文档的json数据,该文档可以导出到支持OAS3.0的工具中,比如apifox

# 注意事项

# 注解

Springdoc-openapi中的注解与Swagger中的注解不同,细微之处可能有些调整

# 拦截器

如果有拦截器注意查看是否拦截了swagger的请求

# https://app.apifox.com/

可以使用apifox 导入swagger的json数据,然后进行接口测试,并且可以导出更友好的接口文档

上次更新: 2024/11/01, 16:22:32

← SpringBoot3项目快速构建 MQ中如何保证消息的顺序性→