前言
Swagger入门与Spring Boot集成Swagger。
简单尝试了Springfox和Springdoc,感觉Springdoc问题更少些,但文档也相对少。
历史
Swagger最初是由Tony Tam在2010年创建的一套开源工具,用于描述和定义RESTful API。Swagger提供了一组注解和元数据,用于描述API的基本信息、接口操作、请求参数、响应模型等。它的目标是提供一种标准的方式来定义和文档化API,以便于开发人员和消费者能够更好地理解和使用API。Tony Tam在2015年加盟SmartBear Software任VP,并将Swagger相关的企业级服务都带到了 SmartBear。
Swagger团队与OpenAPI规范进行了合作,并将Swagger规范作为OpenAPI规范的基础。OpenAPI规范是一个开放标准,用于描述和定义RESTful API的详细信息。它提供了一种机器可读的方式来描述API的结构、路径、请求和响应的参数、模型定义等。OpenAPI规范允许开发人员、工具和平台之间的互操作性,使得API的设计、开发和测试更加统一和便捷。
因此,可以说Swagger是OpenAPI规范的实现之一,Swagger提供了一套工具和框架,使得使用OpenAPI规范来描述和定义API更加简单和方便。通过Swagger工具,您可以生成符合OpenAPI规范的API文档,以及使用Swagger UI界面来浏览和测试API。
用一句话总结:Swagger围绕一个既有的规范,创造了一系列的软件工具,为开发和使用API提供了极大的便利。
Swagger
Swagger是一个规范和完整的框架,一个用于生成、描述、调用和可视化RESTful风格的Web服务。
有三个最知名的工具需要入门者去了解,它们分别是swagger-ui、swagger-editor和swagger-codegen。
1. Swagger UI:
Swagger UI是Swagger的官方工具,用于展示和测试API文档。它提供了一个交互式的界面,使得开发人员和用户可以直观地查看和理解API的各个细节。
Swagger UI的主要特点包括:
- 自动生成交互式API文档界面:Swagger UI根据API的Swagger规范生成一个可交互的网页界面,以展示API的路径、参数、模型定义、请求和响应等信息。
- 支持请求测试:Swagger UI允许用户在界面中直接测试API,通过提供参数、发送请求并查看响应结果,帮助开发人员进行API的调试和测试。
- 多种展示方式:Swagger UI提供了多种展示方式,如可折叠的API路径列表、可切换的主题样式等,使得用户能够以自己喜欢的方式查看和使用API文档。
2. Swagger Editor:
Swagger Editor是Swagger提供的一个在线编辑器,用于编写、定义和验证Swagger规范的API文档。它为开发人员提供了一个方便的界面来创建和编辑API文档,并即时反馈验证结果和错误信息。
Swagger Editor的主要特点包括:
- 在线编辑器:Swagger Editor可以直接在网页中进行API文档的编写和编辑,而无需额外的编辑器或工具。
- 即时验证:Swagger Editor可以即时验证API文档的正确性和合法性,通过检查Swagger规范的语法、格式和规则,提供实时的反馈和错误提示。
- Swagger规范支持:Swagger Editor完全支持Swagger规范,并提供了丰富的自动补全、代码提示和文档辅助功能,使得编写和编辑Swagger规范更加高效和准确。
3. Swagger Codegen:
Swagger Codegen是Swagger提供的一个代码生成工具,用于根据API文档生成各种编程语言的客户端和服务器端代码。它简化了开发人员根据API文档手动编写代码的过程,提高了开发效率和代码的一致性。
Swagger Codegen的主要特点包括:
- 多语言支持:Swagger Codegen支持生成多种编程语言的代码,包括Java、JavaScript、Python、Ruby、C#等,使得开发人员可以根据自己的喜好和需求选择适合的语言。
- 自定义模板:Swagger Codegen允许开发人员根据自己的需求自定义代码生成的模板,以适应不同的编码风格和规范要求。
- 代码生成命令行工具:Swagger Codegen提供了命令行工具,可以方便地从Swagger规范文件生成代码,减少了手动编写代码的工作量。
Springfox
Springfox是一个用于自动生成和展示RESTful API文档的Java库(Spring社区项目,非官方),与Swagger规范兼容,并提供了一套工具使得在Spring Boot应用程序中使用Swagger变得更加简单和便捷。
下面我用一个例子来演示如何在Spring Boot应用中集成Springfox。
1. 引入Springfox依赖
1 | // author: SilenceZheng66 |
2. 创建配置类
1 | // author: SilenceZheng66 |
3. 写个响应类
1 | // author: SilenceZheng66 |
4. 写个控制器
1 | // author: SilenceZheng66 |
5. 启动
直接进入地址 http://localhost:8080/swagger-ui/index.html#/
问题
Springfox在部署过程中,会出现一些问题:
在 Spring Boot3.x.x 下报Servlet缺失错误
报错信息:Type javax.servlet.http.HttpServletRequest not present
原因分析:Spring Boot3要求最低Java17,它使用jakarta命名空间而不是javax,但是Swagger仍然使用旧版本的命名空间。
自Java EE 8起,Java EE已改名为Jakarta EE。Jakarta EE是一个开放的企业级Java平台,由Eclipse Foundation进行管理和发展。它是构建企业级Java应用程序的一组规范和技术。
Jakarta EE使用Jakarta命名空间,以避免与Oracle拥有的Java EE命名空间产生冲突。Jakarta命名空间用于标识与Java EE兼容的API和技术。例如,以前的javax.servlet包已经迁移到了jakarta.servlet包。类似地,其他Java EE规范和API也被迁移到了对应的Jakarta命名空间。
解决方案:添加如下依赖
1 | // author: SilenceZheng66 |
在 Spring Boot2.7.8 下报空指针错误
报错信息:Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null
原因分析:Spring Boot2.6.x 以上的版本默认情况下使用的是基于Servlet的路径匹配方案,该方案使用了PathPatternParser来解析和匹配路径模式。Springfox中关于getPatternsCondition
的代码有问题,导致空指针异常。
PathPatternParser和AntPathMatcher是Spring Framework中用于路径匹配的两个不同的类。
AntPathMatcher是在较早的版本中引入的,它使用Ant风格的路径模式语法进行路径匹配,例如/users/*/profile。它提供了一些功能强大的特性,例如通配符匹配、路径变量、路径扩展等。AntPathMatcher是Spring Framework中常用的路径匹配工具,被广泛用于处理URL路径的匹配和请求映射等场景。
PathPatternParser是在较新的版本中引入的,它提供了更灵活和强大的路径模式解析和匹配功能。它支持多种路径模式语法,包括Ant风格和Servlet风格,并提供了更精确的路径匹配规则。PathPatternParser在设计上更加统一和一致,可以处理更复杂的路径匹配需求,并且与Servlet规范更加兼容。
解决方案:更改Spring MVC的路径匹配策略为AntPathMatcher,在Spring Boot 默认配置文件中增加spring.mvc.pathmatch.matching-strategy=ant_path_matcher
(KV格式)。
Springdoc(推荐)
Springdoc-openapi java库有助于使用 spring boot 项目自动生成 API 文档。 Springdoc通过在运行时检查应用程序以根据 spring 配置、类结构和各种注释推断 API 语义来工作。可以使用 swagger-api 通过注释来自动生成 JSON/YAML 和 HTML 格式 API 的文档。
该库支持:
- OpenAPI 3
- Spring-boot v3 (Java 17 & Jakarta EE 9)
- JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
- Swagger-ui
- OAuth 2
- GraalVM native images
下面演示如何在Spring Boot3.x.x中集成Springdoc,参考文档见这里。
1. 引入Springdoc依赖
1 | // author: SilenceZheng66 |
2. 创建配置类
1 | // author: SilenceZheng66 |
3. 写个响应类
1 | // author: SilenceZheng66 |
4. 写个控制器
1 | // author: SilenceZheng66 |
5. 启动
直接进入地址 http://localhost:8080/swagger-ui/index.html#/
参考
[1] https://swagger.io/resources/open-api/
[2] https://github.com/swagger-api
[3] https://github.com/springfox/springfox
[4] https://blog.csdn.net/long199366/article/details/114388171
[5] http://springfox.github.io/springfox/docs/current/
[6] https://blog.csdn.net/qq_42495847/article/details/121424122
[7] https://stackoverflow.com/questions/71549614/springfox-type-javax-servlet-http-httpservletrequest-not-present
[8] https://blog.csdn.net/m0_52457066/article/details/129094931
[9] https://blog.csdn.net/kkorkk/article/details/123774484
[10] https://springdoc.org/v2/
[11] https://springdoc.org/index.html#migrating-from-springfox
后记
首发于 silencezheng.top,转载请注明出处。