https://docs.discourse.org/openapi.json の OpenAPI / Swagger の検証

https://docs.discourse.org/openapi.json の Swagger が有効でないようです。

再現手順:

数秒後、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"
                             }
「いいね!」 1

取り上げていただきありがとうございます。

いいえ、利用可能な仕様ファイルはこれのみです。

このコミットで Swagger 2.0 から OpenAPI 3.0 へのドキュメント移行を多数変更しました。

しかし、いくつかの項目が見落とされているか、仕様に対する新しい変更の可能性があります。

エラーを確認するために openapi-cli コマンドラインツールでもう一度確認しましたが、Swagger サイトと同様のエラーを再現できました。

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ 検証に失敗しました。エラー 647 件、警告 579 件。

良さそうです。これらの修正を含む パッチを提出 していただければ大変歓迎しますが、私がこれらの一部を整理することもできます。

「いいね!」 4

どういたしまして。ご貢献のレビューにご協力いただきありがとうございます。

当社の SQL エンジンは、API を Discourse へのコネクタとして利用しており、このコネクタは手書きではなく Swagger ベースで構築されていますが、現在は引き続きテスト中です。長さ、データ型、NULL 許容などに関する制約違反の問題が見つかる可能性もあります。

パッチの提出は喜んで行いますが、チームが提案された変更をより徹底的にテストするまで数日お待ちください。そうしなければ、あなたの貴重な時間をあまりにも割いてしまい、効率が低下してしまう恐れがあります。

ありがとうございました!

「いいね!」 3

プルリクエストが送信されました。実際に動作するように調整しているため、以下に示す参照テーブル値など、さらに変更が行われる可能性があります。

「いいね!」 3

このトピックの最終確認をさせていただきます。提出された PR は議論を経てクローズされました。

ただし、改行の問題を修正するコミットを後に行いました。

また、現在、OpenAPI の JSON スペックファイルを自動生成できるツールである rswag を用いて、API ドキュメントを Discourse のコードベースとより 統合された形 に移行する作業を進めています。現在のドキュメントにはいくつかのリンティング上の問題がありますが、これらの問題の多くを解決できる rswag への移行を完了することにリソースを集中させる方が、私たちのエネルギーを効果的に活用できると考えています。

「いいね!」 5

素晴らしいですね!*.yaml やそれ以外のファイルについては対応できませんが、新しい Swagger が公開された際は、十分にテスト・認証を行う必要があります。ご連絡ください。

「いいね!」 1