Validando OpenAPI / Swagger en https://docs.discourse.org/openapi.json

[guidoleenders]

El swagger en https://docs.discourse.org/openapi.json parece no ser válido.

Escenario de reproducción:

• Ve a https://editor.swagger.io/
• Haz clic en Archivo → Importar URL.
• Ingresa la URL.

Después de unos segundos, ocurren 142 errores de validación.

No puedo adjuntar, pero se parece a:

Error estructural en paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.name.description
debería ser una cadena
Saltar a la línea 184
Error estructural en paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.color.description
debería ser una cadena
Saltar a la línea 187
Error estructural en paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.text_color.description
debería ser una cadena
Saltar a la línea 190
... más ...

¿Existe alguna definición swagger alternativa (válida) disponible?

Parche sugerido

A continuación se presenta un parche sugerido hasta ahora.

Resumen

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

Gracias por plantearlo.

@guidoleenders

¿Existe una definición de Swagger alternativa (de validación) disponible?

No, este es el único archivo de especificación disponible.

Realicé muchos cambios para migrar la documentación de Swagger 2.0 a OpenAPI 3.0 en este commit:

Convert from swagger to openapi 3

pero parece que se pasaron por alto algunos aspectos o quizás haya cambios nuevos en la especificación.

Acabo de verificarlo nuevamente con la herramienta de línea de comandos openapi-cli para buscar errores y pude reproducir errores similares a los del sitio de Swagger:

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ La validación falló con 647 errores y 579 advertencias.

@guidoleenders

Lo siguiente es un parche sugerido hasta ahora.

Se ve bien. Si deseas enviar un parche con estas correcciones, sería muy bienvenido, aunque también puedo ayudarte a limpiar algunos de estos problemas.

[guidoleenders]

De nada. Gracias por estar abierto a revisar una contribución.

Nuestro motor SQL utiliza la API como conector hacia Discourse y el conector se basa en Swagger en lugar de estar escrito a mano, pero aún estamos probando cosas. Podríamos encontrar problemas como violaciones de restricciones en términos de longitud, tipo de datos y nulos.

Estaré encantado de enviar un parche, pero esperaré unos días para que el equipo pruebe los cambios sugeridos de manera más exhaustiva. De lo contrario, ocuparía mucho de tu tiempo con poca eficiencia.

¡Gracias!

[guidoleenders]

Se ha enviado la solicitud de cambios. Es posible que lleguen más modificaciones mientras intentamos que funcione, como los valores de la tabla de referencia que se muestran a continuación.

[blake (Blake Erickson)]

Solo cerrando el ciclo sobre este tema. La PR enviada fue cerrada tras una discusión.

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

Pero sí la seguí con un commit que solucionó los problemas de saltos de línea:

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

Además, solo quería mencionar que actualmente estamos en proceso de convertir la documentación de la API para que esté más integrada con la base de código de Discourse mediante una herramienta llamada rswag, que puede generar automáticamente el archivo de especificación JSON de OpenAPI. Sé que hay algunos problemas de linting en la documentación actual, pero creo que lo más productivo sería invertir nuestra energía en completar la transición a rswag, lo cual nos ayudará a resolver muchos de estos problemas.

[guidoleenders]

¡Qué bueno escuchar eso! No podemos manejar archivos *.yaml o similares, pero cuando haya un nuevo Swagger, debemos probarlo/certificarlo exhaustivamente: por favor, avísame.