Validation de l'OpenAPI / Swagger sur https://docs.discourse.org/openapi.json

[guidoleenders]

Le Swagger sur https://docs.discourse.org/openapi.json semble invalide.

Scénario de reproduction :

• Allez sur https://editor.swagger.io/
• Cliquez sur Fichier → Importer une URL.
• Saisissez l’URL.

Après quelques secondes, 142 erreurs de validation apparaissent.

Impossible de joindre le fichier, mais cela ressemble à :

Erreur structurelle à paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.name.description
devrait être une chaîne
Aller à la ligne 184
Erreur structurelle à paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.color.description
devrait être une chaîne
Aller à la ligne 187
Erreur structurelle à paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.text_color.description
devrait être une chaîne
Aller à la ligne 190
... plus ...

Existe-t-il une définition Swagger alternative (validée) disponible ?

Correctif suggéré

Voici un correctif suggéré jusqu’à présent.

Résumé

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

Merci d’avoir soulevé ce point.

@guidoleenders

Existe-t-il une définition Swagger alternative (de validation) disponible ?

Non, c’est le seul fichier de spécification disponible.

J’ai apporté de nombreuses modifications pour passer la documentation de Swagger 2.0 à OpenAPI 3.0 dans ce commit :

Convert from swagger to openapi 3

mais il semble que certaines choses aient été négligées ou qu’il s’agisse peut-être de nouvelles modifications de la spécification.

Je viens de vérifier à nouveau avec l’outil en ligne de commande openapi-cli pour détecter les erreurs, et je parviens à reproduire des erreurs similaires à celles du site Swagger :

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ La validation a échoué avec 647 erreurs et 579 avertissements.

@guidoleenders

Voici un correctif suggéré jusqu’à présent.

Ça a l’air bien. Si vous souhaitez soumettre un correctif avec ces corrections, cela serait très bienvenu, mais je peux aussi aider à nettoyer certains de ces éléments.

[guidoleenders]

Je vous en prie. Merci d’être ouvert à l’examen d’une contribution.

Notre moteur SQL utilise l’API comme connecteur vers Discourse, et ce connecteur est basé sur Swagger plutôt que sur du code écrit à la main, mais nous sommes toujours en phase de test. Nous pourrions rencontrer des problèmes tels que des violations de contraintes en termes de longueur, de type de données et de valeurs nulles.

Je serai ravi de soumettre un correctif, mais j’attendrai quelques jours pour que l’équipe teste plus en profondeur les modifications suggérées. Sinon, je vous ferais perdre beaucoup de temps pour peu d’efficacité.

Merci !

[guidoleenders]

La pull request a été soumise. D’autres modifications pourraient survenir alors que nous tentons effectivement de la faire fonctionner, comme les valeurs de la table de référence illustrées ci-dessous.

[blake (Blake Erickson)]

Je boucle simplement sur ce sujet. La PR soumise a été fermée après une discussion.

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

Mais j’ai suivi avec un commit qui a corrigé les problèmes de sauts de ligne :

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

Je voulais aussi dire que nous sommes actuellement en train de convertir la documentation de l’API pour qu’elle soit plus intégrée à la base de code de Discourse en utilisant un outil appelé rswag, qui peut générer automatiquement le fichier de spécification JSON OpenAPI. Je sais qu’il y a quelques problèmes de linting dans la documentation actuelle, mais je pense que notre énergie serait mieux investie à finaliser la transition vers rswag, ce qui nous aidera à résoudre bon nombre de ces problèmes.

[guidoleenders]

C’est super de l’entendre ! Nous ne pouvons pas traiter les fichiers *.yaml ou similaires, mais lorsqu’une nouvelle version de Swagger est disponible, nous devons la tester et la certifier rigoureusement : merci de me tenir informé.