验证 OpenAPI / Swagger 在 https://docs.discourse.org/openapi.json

[guidoleenders]

https://docs.discourse.org/openapi.json 上的 Swagger 似乎无效。

复现场景：

• 访问 https://editor.swagger.io/
• 点击 文件 → 导入 URL。
• 输入该 URL。

几秒钟后，出现 142 个验证错误。

无法附加文件，但错误类似于：

paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.name.description 处的结构错误
应为字符串
跳转到第 184 行
paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.color.description 处的结构错误
应为字符串
跳转到第 187 行
paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.text_color.description 处的结构错误
应为字符串
跳转到第 190 行
... 更多 ...

是否有可用的替代（有效）Swagger 定义？

建议的补丁

以下是截至目前建议的补丁。

摘要

diff --git "a/discourse-swagger-original.json" "b/discourse-swagger.json"
index f9267f5d0..dcebe3fd8 100644
--- "a/discourse-swagger-original.json"
+++ "b/discourse-swagger.json"
@@ -578,8 +578,8 @@
                         },
                         "available_groups": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -1196,8 +1196,8 @@
                     },
                     "actions_summary": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -1788,8 +1788,8 @@
                               },
                               "actions_summary": {
                                 "type": "array",
-                                "uniqueItems": null,
-                                "minItems": null,
+                                "uniqueItems": false,
+                                "minItems": 0,
                                 "items": {
                                   "type": "object"
                                 }
@@ -1885,8 +1885,8 @@
                         },
                         "stream": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -1899,14 +1899,14 @@
                     },
                     "timeline_lookup": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "properties": {
                           "0": {
                             "type": "array",
                             "uniqueItems": true,
-                            "minItems": null,
+                            "minItems": 0,
                             "items": {
                               "type": "object"
                             }
@@ -3621,8 +3621,8 @@
                   "properties": {
                     "user_badges": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -3798,8 +3798,8 @@
                         },
                         "featured_user_badge_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -3864,8 +3864,8 @@
                   "properties": {
                     "user_badges": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -4041,8 +4041,8 @@
                         },
                         "featured_user_badge_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -4734,8 +4734,8 @@
                           },
                           "posters": {
                             "type": "array",
-                            "uniqueItems": null,
-                            "minItems": null,
+                            "uniqueItems": false,
+                            "minItems": 0,
                             "items": {
                               "type": "object"
                             }
@@ -4745,16 +4745,16 @@
                     },
                     "users": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
                     },
                     "categories": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -4773,24 +4773,24 @@
                         },
                         "post_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
                         },
                         "user_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
                         },
                         "category_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -6406,8 +6406,8 @@
                     },
                     "owners": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -7241,8 +7241,8 @@
                           },
                           "choices": {
                             "type": "array",
-                            "uniqueItems": null,
-                            "minItems": null,
+                            "uniqueItems": false,
+                            "minItems": 0,
                             "items": {
                               "type": "object"
                             }

[blake (Blake Erickson)]

感谢提出这个问题。

@guidoleenders

是否有可用的替代（验证用）Swagger 定义？

没有，这是唯一可用的规范文件。

我在本次提交中做了许多更改，将文档从 Swagger 2.0 迁移到 OpenAPI 3.0：

Convert from swagger to openapi 3

但看起来有些内容被遗漏了，或者可能是规范的新增变更。

我刚刚再次使用 openapi-cli 命令行工具进行验证以检查错误，并成功复现了与 Swagger 站点类似的错误：

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ 验证失败，共发现 647 个错误和 579 个警告。

@guidoleenders

以下是截至目前建议的补丁。

看起来不错。如果您愿意 提交补丁 以应用这些修复，我们将非常欢迎；不过，我也可以协助清理其中一些问题。

[guidoleenders]

不客气。感谢您愿意审阅此次贡献。

我们的 SQL 引擎通过 API 作为与 Discourse 的连接，该连接器基于 Swagger 生成而非手写，但我们仍在进行测试。我们可能会发现一些问题，例如在长度、数据类型和可空性方面的约束冲突。

我很乐意提交补丁，但我会先等待几天，让团队更彻底地测试所建议的更改。否则，这可能会占用您大量时间而收效甚微。

谢谢！

[guidoleenders]

已提交拉取请求。随着我们实际尝试使其运行，可能会有更多变更，例如如下所示的参考表值。

[blake (Blake Erickson)]

就此话题做个收尾。提交的 PR 在讨论后已关闭。

Numerous fixes to make Swagger parseable and comply with data. (#25)

但我随后提交了一个提交，修复了换行问题：

FIX: Update yaml syntax to remove extra newlines in json output

另外，想说明一下，我们目前正在将 API 文档转换为更与 Discourse 代码库集成的形式，使用的工具是 rswag，它可以自动生成 OpenAPI JSON 规范文件。我知道当前文档存在一些代码规范问题，但我觉得将精力投入到完成向 rswag 的过渡是最有效的，这将帮助我们解决其中的许多问题。

[guidoleenders]

太好了！我们无法处理 *.yaml 或其他类型的文件，但每当有新的 Swagger 发布时，我们应该进行全面的测试和认证：请随时告知我。