问题标签 [openapi]

我正在使用 Swagger 和 Scala 来记录我的 REST API。我想为 POST、PUT 和 DELETE 启用批量操作，并希望相同的路由接受单个对象或对象集合作为正文内容。

有没有办法告诉 Swagger 参数是 A 类型值的列表或 A 类型的单个值？

类似于 REST 的可变参数。

Is it possible to group multiple parameters to reference them in multiple routes?

For example I have a combination of parameters which I need in every route. They are defined as global parameters. How can I group them?

I think about a definition like this:

And then reference the whole group in my route:

Is this possible with Swagger 2.0?

我正在尝试使用 Swagger 定义一个接受实际文件和描述文件内容的模式对象的 API。这是 Swagger YAML 的一个片段。但是，它不会在 Swagger 编辑器中验证。

Swagger 编辑器引发以下验证错误：

Swagger 错误：数据与“oneOf”中的任何模式都不匹配

我错过了什么吗？或者这不是 Swagger 支持的功能吗？

我正在为其编写 Swagger 2.0 规范的 API 基本上是任何 JSON 值的存储。

我想要一个读取值的路径和一个存储非预定义深度的任何 JSON 值（null、数字、整数、字符串、对象、数组）的路径。

不幸的是，Swagger 2.0 似乎对输入和输出的模式非常严格，并且不允许 JSON Schema 允许的整个模式集。Swagger 编辑器不允许混合值（例如，可以是布尔值或整数的属性）或松散定义的数组（必须严格定义项目的类型）和对象。

所以我正在尝试通过定义MixedValue模式来解决问题：

但是 Swagger Editor 拒绝松散定义的object和array属性。

问题： - 有没有办法解决这个问题？- 它只是 Swagger 编辑器错误还是 Swagger 2.0 规范的强限制？- 有没有更好的方法（最佳实践）来指定我需要什么？- 我的 API 规范是否可以预期 swagger 为某些语言生成的代码存在一些限制？

我熟悉 Microsoft 堆栈。我将 OData 用于我的一些宁静服务。最近我遇到了 Swagger for API 文档，我试图了解它与 OData 的关系。它们似乎都是 RESTful 规范。哪一种被广泛使用？

我正在尝试为一个时间间隔构建一个 Swagger 模型，使用一个简单的字符串来存储时间（我知道还有 datetime）：

由于某种原因，生成的 HTML 不显示 lowerBound 和 upperBound “描述”，而只显示原始时间“描述”。这让我觉得我没有正确地做到这一点。

所以问题是如果使用模型作为类型实际上可以像我试图做的那样完成。

我在 c# 中有一个 Asp.Net Web API 5.2 项目并使用 Swashbuckle 生成文档。

我有包含继承的模型，例如从 Animal 抽象类和 Dog 和 Cat 类派生的 Animal 属性。

Swashbuckle 只显示 Animal 类的模式，所以我尝试使用 ISchemaFilter （他们也建议这样做），但我无法让它工作，而且我找不到合适的例子。

有人可以帮忙吗？

我的 REST Web 服务中有一个使用 GET 方法的函数，它有两个可选参数。

我试图在 Swagger 中定义它，但在我设置as后遇到错误Not a valid parameter definition。requiredfalse

我发现如果我将required值设置为true错误就会消失。这是我的 Swagger 代码示例。

我没有体验过正文中的参数或查询中的参数。我认为这个问题只与路径中的参数有关。我在 swagger 规范文件中也找不到任何解决方案。

有没有其他方法可以在 Swagger 中定义可选参数，或者我的代码有什么错误？

任何帮助，将不胜感激。

是否可以声明一个自定义响应标头，该标头将出现在所有响应中，而无需在每个响应结构中复制它？

我有一项服务，它可以根据Content-Type标头具有两种不同的主体参数。

例如路径/Pet：

• 如果Content-Type: application/somecustom.resource+json使用，则 POST 可以Pet作为 body 参数。

• 如果Content-Type: application/somecustom.function+json使用，那么 POST 应该采用一些不同的主体参数来调用函数并返回不同的响应。

关于如何在 OpenAPI (Swagger) 中体现这一点的任何建议？