type
status
date
summary
slug
tags
category
icon
password
action编写时用的是open api的接口规范，OpenAPI 规范（原名 Swagger）是一种用于描述 RESTful API 的语言无关接口。这个规范定义了一组规则和规定，用于描述 API 的结构，包括其各种操作、输入和输出参数、身份验证方法等。使用 OpenAPI 规范可以确保 API 的设计符合一定的标准，便于开发、测试和维护。
OpenAPI基本特点
主要特点包括：
- 机器可读性与人类可读性：OpenAPI 文档既可以被机器读取，以生成代码和测试案例，也可以被人阅读，作为 API 的使用说明。
- 格式灵活：可以使用 JSON 或 YAML 格式编写。
- 兼容性：适用于多种语言和框架，促进不同系统间的互操作性。
- 自动化：基于 OpenAPI 规范，可以自动生成客户端库、服务器存根、API 文档以及其他工具。
- 丰富的工具支持：许多工具都支持 OpenAPI 规范，包括 Swagger UI（用于生成可视化文档）、Swagger Codegen（用于生成代码）等。
- 社区支持：由于广泛的采用和社区支持，开发者可以轻松找到解决方案和最佳实践。
- 版本控制：OpenAPI 规范的版本更新提供了向后兼容性和新特性。
通过 OpenAPI 规范，团队可以更有效地设计、开发、测试和文档化 API。这有助于提高开发效率，减少潜在的沟通误解，同时也使得 API 的维护和扩展变得更加容易。
openAPI概念解释：endpoint
在 OpenAPI 规范中，“Endpoints”指的是 API 的具体请求点，也就是 API 用户可以访问的各种不同的 URL 地址。每个 Endpoint 通常对应 API 的一个具体功能或资源。在 RESTful API 中，这些 Endpoints 通常代表了对特定资源的一系列操作。
每个 Endpoint 都与一种 HTTP 方法（如 GET、POST、PUT、DELETE 等）结合使用，以表明对该资源执行的操作类型。例如：
- GET
/users：这个 Endpoint 可能用于获取用户列表。
- POST
/users：这个 Endpoint 可能用于创建一个新用户。
- GET
/users/{userId}：这个 Endpoint 可能用于获取一个特定用户的详细信息。
- PUT
/users/{userId}：这个 Endpoint 可能用于更新一个特定用户的信息。
- DELETE
/users/{userId}：这个 Endpoint 可能用于删除一个特定用户。
在 OpenAPI 文档中，这些 Endpoints 会被详细描述，包括它们的路径、HTTP 方法、输入参数、返回值、可能的响应状态码以及这些响应的具体内容等。这样，API 的消费者可以清晰地理解每个 Endpoint 的作用和使用方式，从而正确地与 API 进行交互。
代码示例讲解open api
openapi示例代码-yaml(json同理）
openapi代码重点解释
openapi: 3.0.0：声明这个文档遵循 OpenAPI 规范 3.0.0 版本。
info：提供 API 的基本信息。title: API 的名称。version: API 的版本。
paths：定义了所有的 API Endpoints。/users：一个 Endpoint，用于列出所有用户。get: 表明这个 Endpoint 响应 GET 请求。summary: 简要描述这个 Endpoint 的功能。responses: 描述可能的响应。'200': HTTP 状态码，表示请求成功。description: 响应的描述。content: 响应内容的类型和结构。
/users/{userId}：另一个 Endpoint，用于获取特定用户的详细信息。parameters: 定义请求参数。in: path: 参数位于 URL 路径中。name: 参数名称。required: 表明这个参数是必须的。schema: 参数的数据类型。
components：用于定义在整个文档中重复使用的结构。schemas: 定义数据模型。User: 一个对象，描述用户的数据结构。properties: 用户对象的属性及其类型。
components如何使用：
在上述的 OpenAPI 示例中，
components 部分用于定义可在整个文档中重用的各种元素。在这个具体的例子中，我们定义了一个 User 数据模型，它在文档的不同地方被引用。让我们详细看看这是如何工作的：- 定义
User模型： 在components下的schemas部分，我们定义了一个User对象模型。这个模型描述了一个用户的数据结构，包含id、name和email这几个属性。
- 在 Endpoint 中引用
User模型： 在paths部分，我们定义了两个操作（GET /users和GET /users/{userId}）。在这些操作的响应中，我们引用了User模型。 - 在
GET /users中，我们指定响应是User对象的数组。 - 在
GET /users/{userId}中，我们指定响应是一个单独的User对象。
在这两个情况中，通过使用
$ref 关键字引用 #/components/schemas/User，我们避免了重复定义用户对象的结构。这样做的好处是，如果用户数据模型发生变化，我们只需要在 components 部分更新 User 模型的定义，而不是在每个使用到该模型的地方都进行修改。总的来说，
components 在这个案例中用于定义一个通用的数据模型（User），然后在不同的 Endpoints 的响应中被重复引用。这样提高了代码的可维护性和可读性。附：Restful api
RESTful API 是一种 API（应用程序编程接口）的设计风格，它遵循 REST（Representational State Transfer，表述性状态传递）的原则。REST 是由 Roy Fielding 在 2000 年在他的博士论文中提出的网络软件架构风格。RESTful API 在网络应用中广泛使用，特别是在构建 Web 服务时。它的核心特点和原则包括：
- 客户端-服务器架构：RESTful API 严格分离客户端和服务器的关注点。这样可以简化客户端的实现，同时提高服务器的可扩展性。
- 无状态性：每个请求从客户端到服务器都应包含所有必要的信息来理解和处理该请求。服务器不应存储请求之间的任何客户端状态。
- 可缓存性：响应应被定义为可缓存的或不可缓存的。这有助于提高客户端和网络的效率。
- 统一接口：RESTful API 应具有统一的接口，这使得从一个服务迁移到另一个服务更加容易。
- 分层系统：客户端通常不能直接与存储数据的服务器交互，而是通过一个或多个中间层进行通信，增加了系统的可伸缩性和安全性。
- 按需代码（可选）：服务器可以临时扩展客户端的功能性，通过发送可执行代码给客户端。
RESTful API 通常使用 HTTP 协议，并通过标准的 HTTP 方法（如 GET、POST、PUT、DELETE）与资源进行交互。在 RESTful 架构中，每个 URL 代表一个资源，这些资源通过这些 HTTP 方法进行操作。例如，一个 URL 可能代表一个特定的用户，而一个 HTTP GET 请求到这个 URL 就可能用于检索该用户的信息。
这种设计风格使得 RESTful API 易于理解和使用，同时也促进了良好的网络性能和可伸缩性。
❗️❗️❗️❗️❗️所有视频首发于抖音：【云哥聊AI】，欢迎关注。
系统学习ChatGPT
建议大家系统学习，现在课程正在秒杀优惠中，全部课程只要199（入门课+进阶课+项目实战+所有资料）点击下方链接了解详情并试听～
免费的AI对话+画图(⬇️Chatgpt+midjourney⬇️）
https://air.chat918.com
学术科研AI神器（大学生、科研人员、职场必备）
🏫https://chat918.com/article/academic_gpt
吐血🩸整理的资料下载：
有关chatgpt安装或者使用上的问题，欢迎您在底部评论区留言，一起交流~
- 作者:云哥
- 链接:https://www.chat918.com/article/openapi
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。
