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

[guidoleenders]

Parece que o Swagger em https://docs.discourse.org/openapi.json não é válido.

Cenário de reprodução:

• Acesse https://editor.swagger.io/
• Clique em File → Import URL.
• Insira a URL.

Após alguns segundos, ocorrem 142 erros de validação.

Não é possível anexar, mas se assemelha a:

Erro estrutural em paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.name.description
deve ser uma string
Ir para a linha 184
Erro estrutural em paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.color.description
deve ser uma string
Ir para a linha 187
Erro estrutural em paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.text_color.description
deve ser uma string
Ir para a linha 190
... mais ...

Existe uma definição Swagger alternativa (válida) disponível?

Patch sugerido

A seguir, um patch sugerido até o momento.

Resumo

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

Obrigado por trazer isso à tona.

@guidoleenders

Existe uma definição swagger alternativa (de validação) disponível?

Não, este é o único arquivo de especificação disponível.

Fiz muitas alterações para migrar a documentação do swagger 2.0 para o openapi 3.0 neste commit:

Convert from swagger to openapi 3

mas parece que algumas coisas foram negligenciadas ou podem ser novas alterações na especificação.

Acabei de verificar novamente com a ferramenta de linha de comando openapi-cli para procurar erros e consegui reproduzir erros semelhantes aos do site swagger:

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ A validação falhou com 647 erros e 579 avisos.

@guidoleenders

O seguinte é um patch sugerido até agora.

Parece bom. Se você quiser enviar um patch com essas correções, será muito bem-vindo, mas também posso ajudar a limpar algumas dessas questões.

[guidoleenders]

De nada. Obrigado por estar aberto a revisar uma contribuição.

Nosso mecanismo SQL usa a API como um conector para o Discourse, e o conector é baseado no Swagger em vez de ser feito manualmente, mas ainda estamos testando as funcionalidades. Podemos encontrar problemas, como violações de restrições em termos de comprimento, tipo de dados e campos nulos.

Ficarei feliz em enviar um patch, mas vou esperar alguns dias para que a equipe teste as alterações sugeridas mais minuciosamente. Caso contrário, eu ocuparia muito do seu tempo com pouca eficiência.

Obrigado!

[guidoleenders]

O pull request foi enviado. Mais alterações podem surgir, pois estamos tentando fazê-lo funcionar, como valores de tabela de referência mostrados abaixo.

[blake (Blake Erickson)]

Apenas fechando o ciclo sobre este tópico. O PR enviado foi fechado após algumas discussões.

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

mas eu fiz um commit de acompanhamento que corrigiu os problemas de quebra de linha:

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

Além disso, só queria dizer que estamos atualmente no processo de converter a documentação da API para ficar mais integrada à base de código do Discourse, usando uma ferramenta chamada rswag, que pode gerar automaticamente o arquivo de especificação JSON OpenAPI. Sei que há alguns problemas de linting na documentação atual, mas sinto que nossa energia seria melhor investida na conclusão da transição para o rswag, o que nos ajudará a resolver muitos desses problemas.

[guidoleenders]

Ótimo saber! Não conseguimos lidar com arquivos *.yaml ou similares, mas quando houver um novo Swagger, devemos testar/certificar minuciosamente: por favor, me avise.