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

guidoleenders · November 9, 2020, 2:47pm

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 · November 9, 2020, 10:21pm

Thanks for bringing this up.

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:

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.

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 · November 9, 2020, 11:19pm

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 · November 17, 2020, 7:31am

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 · January 4, 2021, 5:16pm

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 · January 4, 2021, 5:44pm

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.

Topic		Replies	Views
Broken wizard_builder_spec and application_controller_spec on local machine Dev	6	1406	September 26, 2019
Apt-get update fails inside container yarn repo not signed Bug	27	7432	February 25, 2023
Some users get javascript errors when trying to load our Discourse Support	2	3200	January 16, 2023
Discourse 2.8.4 NoMethodError undefined method `min_tags_from_required_group' Installation unsupported-install	7	362	November 19, 2023
Problems while updating from 3.0.0 to 3.0.1 Installation	16	1151	June 14, 2023

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

Suggested patch

Related topics