Validierung von OpenAPI / Swagger auf https://docs.discourse.org/openapi.json

guidoleenders · 9. November 2020 um 14:47

Das Swagger-Schema unter https://docs.discourse.org/openapi.json scheint nicht gültig zu sein.

Reproduktionsszenario:

Gehe zu https://editor.swagger.io/
Klicke auf Datei → URL importieren.
Gib die URL ein.

Nach einigen Sekunden treten 142 Validierungsfehler auf.

Ich kann keine Datei anhängen, aber es sieht folgendermaßen aus:

Strukturfehler bei paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.name.description
sollte ein String sein
Springe zu Zeile 184
Strukturfehler bei paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.color.description
sollte ein String sein
Springe zu Zeile 187
Strukturfehler bei paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.text_color.description
sollte ein String sein
Springe zu Zeile 190
... weitere ...

Gibt es eine alternative (gültige) Swagger-Definition?

Vorgeschlagener Patch

Im Folgenden ist ein bisher vorgeschlagener Patch aufgeführt.

Zusammenfassung

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 · 9. November 2020 um 22:21

Danke, dass du das angesprochen hast.

Nein, dies ist die einzige verfügbare Spezifikationsdatei.

Ich habe in diesem Commit viele Änderungen vorgenommen, um die Dokumentation von Swagger 2.0 auf OpenAPI 3.0 zu aktualisieren:

aber es scheint, als wären einige Dinge übersehen worden oder es handelt sich möglicherweise um neue Änderungen an der Spezifikation.

Ich habe es gerade erneut mit dem Befehlszeilentool openapi-cli überprüft, um nach Fehlern zu suchen, und ich kann ähnliche Fehler wie auf der Swagger-Website reproduzieren:

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ Validierung fehlgeschlagen mit 647 Fehlern und 579 Warnungen.

Sieht gut aus. Wenn du einen Patch einreichen möchtest, um diese Fehler zu beheben, wäre das sehr willkommen. Ich kann aber auch helfen, einige dieser Punkte zu bereinigen.

guidoleenders · 9. November 2020 um 23:19

Gerne geschehen. Vielen Dank, dass Sie bereit waren, einen Beitrag zu überprüfen.

Unsere SQL-Engine nutzt die API als Connector für Discourse. Der Connector basiert auf Swagger und wurde nicht von Hand geschrieben, doch wir testen derzeit noch verschiedene Aspekte. Es könnte sein, dass wir Probleme wie Verletzungen von Constraints in Bezug auf Länge, Datentyp und Nullable-Felder feststellen.

Ich würde gerne einen Patch einreichen, warte jedoch noch einige Tage, damit das Team die vorgeschlagenen Änderungen gründlicher testen kann. Andernfalls würde ich Ihnen nur wenig effizient viel Zeit abfordern.

Vielen Dank!

guidoleenders · 17. November 2020 um 07:31

Pull-Request wurde eingereicht. Weitere Änderungen können folgen, da wir tatsächlich versuchen, es zum Laufen zu bringen, wie z. B. Referenztabellenwerte, wie unten gezeigt.

blake · 4. Januar 2021 um 17:16

Ich schließe hiermit den Kreis zu diesem Thema. Der eingereichte PR wurde nach einer Diskussion geschlossen.

Ich habe jedoch mit einem Commit nachgelegt, der die Probleme mit den Zeilenumbrüchen behoben hat:

Außerdem wollte ich noch sagen, dass wir derzeit dabei sind, die API-Dokumentation durch die Verwendung eines Tools namens rswag besser in die Discourse-Codebasis zu integrieren. Mit rswag kann die OpenAPI-JSON-Spezifikationsdatei automatisch generiert werden. Ich weiß, dass es bei den aktuellen Dokumenten einige Linting-Probleme gibt, aber ich bin der Meinung, dass es am besten wäre, unsere Energie in den Abschluss des Übergangs zu rswag zu investieren, was uns helfen wird, viele dieser Probleme zu beheben.

guidoleenders · 4. Januar 2021 um 17:44

Schön zu hören! Wir können keine *.yaml- oder ähnliche Dateien bearbeiten, aber wenn ein neuer Swagger verfügbar ist, sollten wir ihn gründlich testen/zertifizieren: Bitte gib mir Bescheid.

Thema		Antworten	Aufrufe
Discourse openapi.json Docs does not follow OpenAPI 3.1.0 spec Bug rest-api	3	486	3. April 2024
Swagger, WADL or similar for the REST API? Development	10	14728	30. August 2016
Contributing to the Discourse API documentation Contributing rest-api , how-to	4	3248	2. April 2024
Missing field 'text' (in 'mainEntity.suggestedAnswer') Bug	29	387	12. Mai 2026
Google Structured Data -- Invalid Article Schema Support	44	8880	9. November 2018

Validierung von OpenAPI / Swagger auf https://docs.discourse.org/openapi.json

Vorgeschlagener Patch

Verwandte Themen