Validating OpenAPI / Swagger on https://docs.discourse.org/openapi.json

[guidoleenders]

The swagger on https://docs.discourse.org/openapi.json is not valid it seems.

Reproduction scenario:

• Go to https://editor.swagger.io/
• Click on File -> Import URL.
• Enter the URL.

After a few seconds, 142 validation errors occur.

Can not attach, but resembles:

Structural error at paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.name.description
should be string
Jump to line 184
Structural error at paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.color.description
should be string
Jump to line 187
Structural error at paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.text_color.description
should be string
Jump to line 190
... more ...

Is there an alternative (validating) swagger definition available?

Suggested patch

The following is a suggested patch sofar.

Samenvatting

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

Thanks for bringing this up.

@guidoleenders

Is there an alternative (validating) swagger definition available?

No, this is the only spec file available.

I did make many change to bring the docs from swagger 2.0 to openapi 3.0 in this commit:

Convert from swagger to openapi 3

but looks like some things were overlooked or are possibly new changes to the spec.

I just verified again with the openapi-cli command line tool to check for errors and I’m able to reproduce similar errors as the swagger site:

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ Validation failed with 647 errors and 579 warnings.

@guidoleenders

The following is a suggested patch sofar.

Looks good. If you’d like to submit a patch with these fixes that would be very welcome, but I can also help clean up some of these.

[guidoleenders]

You are welcome. Thanks for being open to review a contribution.

Our SQL engine uses the API as a connector into Discourse and the connector is based upon Swagger instead of handwritten, but we are still testing stuff. We might find issues such as constraint violations in terms of length, data type and nullable.

I will be happy to submit a patch, but I will wait a few days for the team to test the suggested changes more throughly. Otherwise I would take up a lot of your time with little efficiency.

Thanks!

[guidoleenders]

Pull request was submitted. More changes may come as we are actually trying to get it running, like reference table values as shown below.

[blake (Blake Erickson)]

Just closing the loop on this topic. The submitted PR was closed after some discussion.

https://github.com/discourse/discourse_api_docs/pull/25

but I did follow it up with a commit that fixed the newline issues:

https://github.com/discourse/discourse_api_docs/commit/c5f7b9e3c8b3791b4cdc1c0f16add98cfd9f9f37

Also, just wanted to say that we are currently in the process of converting the api docs to be more integrated with the discourse code base by using a tool called rswag, that can auto generate the OpenAPI json spec file. I know there are some linting issues with the current docs, but I feel like our energy would be best spent investing in completing the transition to rswag which will help us address many of these issues.

[guidoleenders]

Great to hear! We are unable to do the *.yaml or something files, but when there is a new Swagger we should thoroughly test/certify: please let me know.