问题标签 [openapi]

我有一条使用复杂模型的路径，每个 http 方法具有几乎相同的属性。问题是我想为 PUT 和 POST 的请求定义一些必需的属性，而 GET 响应中不需要任何属性（因为服务器总是返回所有属性，并且在文档的其他地方提到了它）。

我创建了一个简单的 cat API 来演示我的尝试。这个想法是，对于 GET 响应，响应模型没有任何标记为必需的，但 PUT 的请求必须具有猫的名称。

Swagger Editor 说这是一个有效的规范，但是name根据 GET 和 PUT 的要求进行设置。Swagger UI 也是如此。

我还尝试了以下版本的 PutCat：

但现在一切都是可选的。

我想不通。有没有办法正确地做到这一点？

编辑：

正如Helen正确提到的，我可以使用readOnlyGET 和 PUT 来解决这个特殊情况。

但是假设我添加了必须为 PUTbreed提供的属性（除了属性之外）。name然后我添加 PATCH 方法，该方法可用于更新其中一个breed或name同时另一个保持不变，并且我不想根据需要设置任何一个。

如何将属性指定为 null 或引用？讨论如何使用 jsonschema 将属性指定为 null 或引用。

我希望用招摇来做同样的事情。

回顾上面的答案，使用 jsonschema，可以这样做：

答案的关键在于使用oneOf.

我的问题的关键点：

1. 我有一个复杂的对象，我想保持 DRY，所以我把它放在定义部分，以便在我的招摇规范中重用：其他属性的值；响应对象等

2. 在我的规范中的各个地方，属性可能是对此类对象的引用或为空。

如何使用不支持oneOfor 的 Swagger 指定它anyOf？

注意：一些 swagger 实现使用x-nullable（或类似的）来指定属性值可以为 null，但是，将对象$ref 替换为它引用的对象，因此看起来任何使用 ofx-nullable都会被忽略。

我正在努力使用 swagger 的语法来描述响应类型。我要建模的是具有动态键和值的哈希映射。这是允许本地化所必需的。语言可能会有所不同，但应始终提供英语。

响应在 JSON 中如下所示：

我的第一次尝试看起来像那样，但我不知道如何写这个名字的部分。AdditionalProperties 似乎是一个关键，但我无法理解它。在这种语法中，对英文文本的要求对我来说也是一个谜，并且该示例似乎也没有按预期工作。它会在 UI 中生成一个空的 $folded:。

但这会产生：

这也没有任何线索表明结果将以语言代码作为键，将文本作为哈希映射的值。

阅读这篇关于使用 OpenAPI (Swagger) 规范描述 REST API的帖子（请参阅：3 How to use a single definition when... ），您可以注意如何使用readOnly属性保留单个资源表示以添加/更新和获取资源有一种表示用于获取（获取集合项）和另一种表示用于添加（POST 到集合）。例如，在下面的 User 单一表示中，id是一个只读属性，这意味着它不会在创建用户时在表示中发送，而是在检索用户时存在。

保持资源表示列表尽可能短真的很干净而且很好，所以我想保持单一资源表示方法，但我面临的问题是：当一个属性对于输入来说是强制性的时如何管理required ? 假设我需要在创建用户时根据需要设置company_data (POST /users/)，但在检索用户时不需要设置 (GET /users/{user_id})。OpenAPI 规范中有什么方法可以在不丢失单一资源表示的情况下满足这种需求？

尽管我在OpenAPI 规范中看到了示例：

对我来说，为什么使用additionalPropertiesMap/Dictionary 的正确模式并不明显。

规范必须说的唯一具体的事情也无济于事additionalProperties：

以下属性取自 JSON Schema 定义，但它们的定义已根据 Swagger 规范进行了调整。它们的定义与 JSON Schema 的定义相同，只是在原始定义引用 JSON Schema 定义的地方，使用了 Schema Object 定义。

• 项目
• 所有的
• 特性
• 附加属性

在使用 swagger2 (openAPI) 构建 rest api 时，我希望允许查询参数 station_id 支持以下内容：

• ?station_id=23（返回站 23）
• ?station_id=23,45（返回站 23 和 45）
• ?station_id=[3:14]（返回站 3 到 14）
• ?station_id=100%（%s 充当通配符，因此返回 1001、10049 等内容）

我使用以下招摇定义（字符串数组）来尝试完成此操作：

使用此定义，除了 ?station_id=23 之外，所有前面的示例都可以工作，因为 swagger 验证失败并显示以下消息：

请注意，如果我引用 station_id 像 ?station_id='23' 验证通过，我会得到正确的响应。但我真的不想使用引号。像联合类型这样的东西可以帮助解决这个问题，但据我所知，它们不受支持。

我还有另一个端点 /stations/{id} 可以处理单个 id 的情况，但仍然有许多其他（非主键）数字字段我想以上面指定的方式过滤。例如 station_latitude。

任何解决方法的想法 - 也许我可以以某种方式使用模式（正则表达式）？如果在 swagger 定义中没有解决方法，是否有办法调整或绕过验证器？这是一个使用swagger-node的 nodejs 项目，我已将swagger-express-mw的版本升级到 0.7.0。

在我的 Swagger 规范文件中，我想返回示例响应，因为我可以添加examples响应。但这使我的规范文件很大并且容易出错。有没有办法引用包含示例对象的 JSON 的文件？

我尝试了类似下面的方法，但它似乎不起作用。

我正在为具有 OpenAPI (Swagger) 定义的 REST API 构建一个模糊器。

我想测试 OpenAPI 定义中的所有可用路径，生成数据以测试服务器，分析响应代码和内容，并验证响应是否符合 API 定义。

我正在寻找一种从模型定义中生成数据（JSON 对象）的方法。

例如，给定这个模型：

我想生成随机数据并得到这样的东西：

我想在我的 OpenAPI / Swagger 定义中表示 2 条路径：

• /resourceA/{id} 其中 id 是一个整数
• /resourceA/{name} 其中名称是一个字符串

两条路径导致相同的结果：检索 resourceA 实例但使用不同的主键。

使用以下 Swagger 定义：swagger: '2.0'

这两个定义之间有很多重复，因为它们代表相同的端点，只是具有不同的路径参数名称/类型。

此外，swagger 编辑器对此定义不满意，我收到以下错误：

我如何表示这一点以将重复减少到最低限度？

是否有任何关于 URL 的规范或约定swagger.json（或任何约定的名称），以便可以自动发现我网站的公共 API？