1 .Swagger
-
简介: Swagger 是一个广泛使用的开源项目，用于生成RESTful API的文档。它通过注解或代码扫描自动生成描述API的文档，包括可视化的接口文档、接口测试功能等。
-
核心工具:
- Swagger Specification (OpenAPI 2.0) : 一种定义API的标准格式。
- Swagger UI: 提供一个用户友好的Web界面，方便开发者和用户浏览API文档。
- Swagger Editor: 用于编辑Swagger规范的在线编辑器。
2. OpenAPI
- 简介: OpenAPI 是一个由Swagger规范演变而来的API描述规范。Swagger 2.0开始被称为OpenAPI 2.0，之后Swagger项目逐渐被OpenAPI Initiative接管，OpenAPI 3.0版本是其后续演进的版本。
- 核心点: OpenAPI 是一个标准，而Swagger则是围绕这个标准的实现工具。
3. Springfox
- 简介: Springfox 是一个与Spring框架集成的开源项目，用于自动生成基于Swagger规范的API文档。它支持生成Swagger 2.0规范的API文档。
- 与Swagger的关系: Springfox 主要用于在Spring项目中轻松集成Swagger，通过注解来自动生成符合Swagger规范的文档。
- 状态: 目前Springfox已经停止更新，社区更多转向其他更现代的解决方案如Springdoc OpenAPI。
4. Knife4j
- 简介: Knife4j 是一个基于Springfox的增强版，用于生成更加美观和功能丰富的API文档界面。它最初是为了解决Springfox中一些功能和界面上的不足而开发的。
- 与Springfox的关系: Knife4j 在Springfox基础上进行了大量优化，并增加了许多高级功能，用户体验更好。
总结：
- Swagger 提供了API文档的规范和实现工具，是API文档生成的基础。
- OpenAPI 是Swagger规范的进化版，是API文档生成的核心标准。
- Springfox 是Spring生态中用于集成Swagger的工具，但已经不再更新。
- Knife4j 是在Springfox基础上进行优化的一个增强版工具，提供了更好的UI和功能。
补充
api规范是个啥
API规范的定义
API规范（例如OpenAPI/Swagger规范）是一种标准化的格式，用于描述你的API，包括其路径、方法、请求参数、响应格式、安全机制等。它是一种机器可读的文档格式，用来精确描述你的API接口，确保开发者、测试人员、文档编写者以及自动化工具能够准确理解并使用你的API。
API规范 vs. API实现
API实现: 是你在代码中实际编写的接口逻辑。你定义了API的路径（endpoint）、请求方法（GET, POST等）、参数、业务逻辑、响应内容等。这部分是你作为开发者通过代码来实现的。 API规范: 是对你实现的API的结构化描述。它将你在代码中实现的接口信息，以一种标准化的方式描述出来，使得其他人或工具可以理解和使用这些信息。
Swagger/OpenAPI 规范与工具的关系
Swagger 或 OpenAPI 是一种规范，定义了如何描述API的文档格式。这种文档不仅供人阅读，还可以被工具（如Swagger UI, OpenAPI Generator）解析和使用。 Swagger UI/Knife4j: 是基于这些规范的工具，它们可以自动读取并解析API规范（通常是一个JSON或YAML文件），并生成用户友好的接口文档页面，让开发者或测试人员可以直观地浏览和测试API。
你写的API与API规范的关系
你在代码中实现API的时候，通常会用注解或其他方法来描述API的请求方法、路径、参数和响应格式。这些注解或描述信息可以自动生成符合 OpenAPI 或 Swagger 规范的文档。 生成的文档就是API规范，它详细描述了你的API的所有细节，可以被工具使用来生成文档页面、测试客户端，甚至生成API的客户端代码。
总结
API规范是对你编写的API接口的标准化描述，而不是对接口的实际实现。
Swagger/Knife4j等工具，利用API规范生成可视化的文档页面和测试界面，帮助你和其他人更好地理解和使用API。
API规范不是你手动写的接口代码，而是对这些接口的描述，是通过工具或手动编写的标准化文档（通常是JSON或YAML格式）。
因此，API规范是你接口实现的“描述文件”，而Swagger/Knife4j等工具帮助你利用这些描述文件生成文档和其他工具支持，以方便开发、测试和集成。
openapi2和openapi3的区别
OpenAPI 2.0 和 3.0 是 OpenAPI 规范的两个主要版本。OpenAPI 3.0 是 OpenAPI 2.0 的演进版本，做了许多改进和增强，主要体现在以下几个方面：
1. 文件结构和语法改进
- OpenAPI 2.0: 主要基于 JSON 或 YAML 格式，使用
swagger: "2.0"作为顶级属性，定义 API 的结构。 - OpenAPI 3.0: 采用更灵活和直观的文件结构，顶级属性改为
openapi: "3.0.0"，并引入了更多语法改进，使文档更加简洁和易读。
2. 路径和操作（Paths and Operations）
- 2.0:
paths下定义每个路径的具体操作，如 GET、POST、PUT 等，但参数定义相对繁琐。 - 3.0: 引入了
components概念，将可重用的组件（如schemas、parameters、responses）集中管理，减少重复定义，并使得文档更模块化。
3. 数据类型和模式（Schema）
- 2.0: 使用
definitions来定义数据结构，支持基本的数据类型（string, integer, boolean 等）。 - 3.0: 更丰富的
schema定义，支持更复杂的数据类型（如oneOf、anyOf、not），以及增强的nullable支持，可以更准确地描述API的请求和响应格式。
4. 请求体（Request Body）
- 2.0: 在 2.0 中，请求体使用
parameters中的in: body来定义，但对于不同的内容类型（如application/json和application/xml），无法灵活地支持多种媒体类型。 - 3.0: 专门引入了
requestBody字段，支持多种媒体类型（content属性），并能详细描述请求体的结构、示例和格式，增强了对复杂请求体的支持。
5. 响应（Responses）
- 2.0: 响应部分相对简单，只能定义一个媒体类型。
- 3.0: 支持为每种响应类型定义多个媒体类型，并且可以为每个媒体类型提供详细的 schema 和示例，响应内容的定义更加灵活和强大。
6. 安全机制（Security）
- 2.0: 支持基本的安全机制（如 API key, OAuth2），但配置相对简单。
- 3.0: 扩展了安全定义，提供了更复杂的 OAuth2 流程定义（如
implicit,password,clientCredentials,authorizationCode），并且安全机制的配置更加细化和可重用。
7. 扩展（Extensions）
- 2.0: 允许通过
x-前缀的自定义属性进行扩展，但不够规范化。 - 3.0: 更加鼓励使用扩展属性，并且可以更加标准化地定义自定义行为。
8. 联接（Links）
- 2.0: 没有内置支持操作之间的联接。
- 3.0: 引入了
links概念，使得可以在响应中定义对其他操作的引用，支持描述操作之间的关系，增强了API文档的表达能力。
9. 标签和分组（Tags and Grouping）
- 2.0: 使用
tags对 API 进行分组，但管理起来不够灵活。 - 3.0: 对标签管理进行了增强，支持更多的元数据，使得 API 文档的组织更加直观和易于导航。
10. 文档示例（Examples）
- 2.0: 示例通常嵌入到响应或请求中，定义较为有限。
- 3.0: 引入了
example和examples字段，支持为不同媒体类型定义多个示例，并可以在各个部分（如请求体、响应体、参数）中使用这些示例，提高了文档的可读性。
总结
OpenAPI 3.0 相比 2.0 进行了大量的改进，使得API文档更加灵活、模块化和易于管理。3.0 版本不仅在语法上更加直观，还增强了对复杂API场景的支持，更加适应现代化的API设计需求
