问题标签 [openapi]

我想用 Swagger 发布一个 json 正文，如下所示：

目前，我有这个定义：

但是数据是在 URL 中发送的。这里是 Swagger 提供的生成 curl ：

我知道query关键工作不好，但我没有找到发布 JSON 正文的方法。我试过formData了，但没有用。

我正在尝试将 Atom 发布协议 (RFC5023) 转换为 Swagger / OpenAPI 规范来练习编写这些规范。

我遇到了以下问题：在 Atom 中有不同类型的 URI，例如 Collection 和 Member URI。我的想法是像这样记录它：

当我这样做时，swagger-editor 声称

等效路径已存在：/{MemberURI}

这些是不同类型的 URI，在查询时会返回不同的内容。我想以不同的方式称呼它们以单独记录它们。

有没有办法做到这一点？

谢谢！

编辑：规范在 Swagger-UI 中显示得很好——这是编辑器中的错误还是 UI 只是忽略了我的错误？

我有一个这样的网址：

在此 URL 中，/id/{idnumber}是 API 基本路径，/status是资源。

我知道 OpenAPI (Swagger) 允许路径中的参数，如下所示：

但这不是我需要的，因为/id/{idnumber}它是基本路径而不是资源路径的一部分。

有没有办法在基本路径中有一个参数？

我想通过我的 API 从我的数据库中请求一个表。但是，我不知道该表将有多少列，或者它将包含什么。如何在 Swagger 中指定这个？这就是我想做的：

关于如何定义没有特定参数的 JSON 对象的任何想法？

我希望几乎所有路径都有以下 3 个通用错误响应。我如何在 Swagger 中描述它而不到处复制粘贴这些行？

我如何在请求中使用它的示例：

我需要使用 Swagger 记录一个 API，该 API 将对象映射用作输入和输出，并由字符串键索引。

例子：

"foo" 和 "bar" 可以是任何字符串键，但它们在键集中应该是唯一的。

我知道，使用 Swagger，我可以定义一个对象数组，但这提供了不同的 API，因为我们将拥有如下内容：

我已阅读“开放 API 规范”-“添加对地图数据类型 #38 的支持”页面。据我了解，它建议使用附加属性，但它似乎无法满足我的需求（或者它不适用于我使用的 Swagger UI 2.1.4）。我错过了什么？

到目前为止，我已经找到了以下解决方法（在 Swagger JSON 中）：

这几乎可以完成这项工作，但读者必须了解“key”可以是任何字符串，并且可以重复多次。

有没有更好的方法来实现我所需要的？

我正在寻找一种方法来为使用 Swagger/OpenAPI 指定的 API 中使用的 JSON 对象声明扩展元数据（或者如果有其他格式支持所请求的功能，则类似的东西）。

想法是使用此元数据自动/部分生成用于编辑此数据的用户界面。

要求的功能列表：

• 对用户可读信息（如名称、描述、占位符、示例）的多语言支持——API 规范本身的名称和描述可能与最终用户（例如 CRUD 编辑器）应该看到的不同。

• 验证元数据
  我知道 Swagger/OpenAPI 中有各种字段，例如最小值、最大值、模式等——但无法为验证指定特定的（多语言）错误消息（例如“用户名必须由字母和数字组成”仅”以及多种语言的翻译）。或要匹配的多个模式（彼此关联的错误消息）。

  另一种验证方法可能是自身的 API 调用（例如检查电子邮件或用户名是否可用）

• 关系元数据 例如，ID 字段实际上是指另一个对象的 ID（具有自己的元数据）。

这个问题不是（Swagger - Specify Optional Object Property or Multiple Responses）的重复，因为该 OP 试图返回 200 或 400。

我有GET一个可选参数；例如，GET /endpoint?selector=foo。

我想返回一个 200，其架构根据参数是否被传递而不同，例如：

在 yaml 中，我尝试使用两个 200 代码，但查看器将它们压扁，就好像我只指定了一个一样。

有没有办法做到这一点？

编辑：以下似乎相关：https ://github.com/OAI/OpenAPI-Specification/issues/270

我正在 Swagger Editor 中编写 OpenAPI 定义。

我的类型定义之一包含一个数组，其中包含与父元素相同类型的子元素。即是这样的：

但是，Swagger 编辑器不会获取children数组中的递归引用，它只是显示为“未定义”元素的数组。

有人知道如何做到这一点吗？

问题陈述：

出于“奇怪”的原因，我们对 API 的所有操作都有不同的“主机”。我们有这样的 API：

• 操作 1：获取 https://host1:port1/api/resources
• 操作 2：获取 https://host1:port2/api/resources/{id}
• 操作 3：POST https://host2:port3/api/resources
• 操作 4：POST https://host2:port4/api/resources/search

如果我们按原样使用 Swagger/OpenAPI，则意味着每个操作创建一个 Swagger/OpenAPI 规范，导致每个操作有一个 swagger-ui 页面，然后需要重新创建一个索引页面来列出一个操作的所有操作API :-/ 这正是我们想要避免的。

问题：

1/ 这个特性——在“/{path}”级别覆盖“host”和“basePath”——有意义吗？

2/ 是否有人已经尝试在 swagger-ui 中实现此功能？

3/ 我可以/应该对 OpenAPI 提出这种改变吗？

欢迎任何其他有用的评论/评论;-)