Validazione di OpenAPI / Swagger su https://docs.discourse.org/openapi.json

[guidoleenders]

Il file Swagger su https://docs.discourse.org/openapi.json non sembra essere valido.

Scenario di riproduzione:

• Vai su https://editor.swagger.io/
• Clicca su File → Import URL.
• Inserisci l’URL.

Dopo pochi secondi, si verificano 142 errori di convalida.

Non è possibile allegare, ma assomiglia a:

Errore strutturale in paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.name.description
dovrebbe essere una stringa
Vai alla riga 184
Errore strutturale in paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.color.description
dovrebbe essere una stringa
Vai alla riga 187
Errore strutturale in paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.text_color.description
dovrebbe essere una stringa
Vai alla riga 190
... altro ...

Esiste una definizione Swagger alternativa (validata) disponibile?

Patch suggerita

Di seguito è riportata una patch suggerita finora.

Riassunto

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)]

Grazie per aver sollevato la questione.

@guidoleenders

Esiste una definizione swagger alternativa (validata) disponibile?

No, questo è l’unico file di specifica disponibile.

Ho apportato molte modifiche per portare la documentazione da swagger 2.0 a openapi 3.0 in questo commit:

Convert from swagger to openapi 3

ma sembra che alcune cose siano state trascurate o che si tratti di possibili nuove modifiche alla specifica.

Ho appena verificato di nuovo con lo strumento da riga di comando openapi-cli per controllare gli errori e riesco a riprodurre errori simili a quelli del sito swagger:

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ La convalida è fallita con 647 errori e 579 avvisi.

@guidoleenders

Di seguito è riportato un patch suggerito finora.

Sembra tutto a posto. Se desideri inviare una patch con queste correzioni, saremmo molto lieti, ma posso anche aiutarti a sistemare alcune di queste.

[guidoleenders]

Prego. Grazie per essere disponibile a revisionare il contributo.

Il nostro motore SQL utilizza l’API come connettore per Discourse; il connettore è basato su Swagger invece che scritto a mano, ma stiamo ancora testando varie cose. Potremmo riscontrare problemi come violazioni dei vincoli in termini di lunghezza, tipo di dati e campi nullabili.

Sarò felice di inviare una patch, ma aspetterò alcuni giorni affinché il team possa testare più approfonditamente le modifiche suggerite. Altrimenti, rischierei di occupare molto del tuo tempo con poca efficienza.

Grazie!

[guidoleenders]

La pull request è stata inviata. Potrebbero arrivare ulteriori modifiche mentre stiamo cercando di farla funzionare, come i valori della tabella di riferimento mostrati di seguito.

[blake (Blake Erickson)]

Chiudo semplicemente il cerchio su questo argomento. La PR inviata è stata chiusa dopo alcune discussioni.

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

Tuttavia, ho seguito con un commit che ha risolto i problemi relativi agli a capo:

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

Inoltre, volevo solo dire che stiamo attualmente convertendo la documentazione API per renderla più integrata con il codice di Discourse utilizzando uno strumento chiamato rswag, che può generare automaticamente il file di specifica JSON OpenAPI. So che ci sono alcuni problemi di linting nella documentazione attuale, ma ritengo che la nostra energia sarebbe meglio spesa investendo nel completamento della transizione verso rswag, che ci aiuterà a risolvere molti di questi problemi.

[guidoleenders]

Bene, è una bella notizia! Non possiamo gestire file come *.yaml o simili, ma quando esce una nuova specifica Swagger dovremmo testarla e convalidarla approfonditamente: fammi sapere.