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

**URL:** <https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612>\
**Category:** Bug\
**Tags:** rest-api\
**Created:** [November 9, 2020, 2:47pm UTC](https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612 "2020-11-09T14:47:44Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![guidoleenders](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/guidoleenders/32/196268_2.png) [@guidoleenders](https://meta.discourse.org/u/guidoleenders)\
**Post date:** [November 9, 2020, 2:47pm UTC](https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612/1 "2020-11-09T14:47:44Z")

</div>

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

Reproduction scenario:

- Go to [https://editor.swagger.io/](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:

```plaintext
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**
>
> ```patch
> 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"
> }
> 
> ```

---

<div class="post-metadata">

**Author:** ![blake](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/blake/32/157322_2.png) [@blake](https://meta.discourse.org/u/blake)\
**Post date:** [November 9, 2020, 10:21pm UTC](https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612/3 "2020-11-09T22:21:24Z")

</div>

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:

[https://github.com/discourse/discourse\_api\_docs/commit/9d688aaaf2484be7e6fcd139be5da0bef079e103](https://github.com/discourse/discourse_api_docs/commit/9d688aaaf2484be7e6fcd139be5da0bef079e103)

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

I just verified again with the [openapi-cli](https://github.com/Redocly/openapi-cli) command line tool to check for errors and I’m able to reproduce similar errors as the swagger site:

```plaintext
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](https://github.com/discourse/discourse_api_docs#contributing) with these fixes that would be very welcome, but I can also help clean up some of these.

---

<div class="post-metadata">

**Author:** ![guidoleenders](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/guidoleenders/32/196268_2.png) [@guidoleenders](https://meta.discourse.org/u/guidoleenders)\
**Post date:** [November 9, 2020, 11:19pm UTC](https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612/4 "2020-11-09T23:19:44Z")

</div>

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!

---

<div class="post-metadata">

**Author:** ![guidoleenders](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/guidoleenders/32/196268_2.png) [@guidoleenders](https://meta.discourse.org/u/guidoleenders)\
**Post date:** [November 17, 2020, 7:31am UTC](https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612/5 "2020-11-17T07:31:34Z")

</div>

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

 ![image](https://global.discourse-cdn.com/meta/original/3X/2/4/24dbb5e53d92a4367706c01c18bcc9ead4f77615.png)

---

<div class="post-metadata">

**Author:** ![blake](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/blake/32/157322_2.png) [@blake](https://meta.discourse.org/u/blake)\
**Post date:** [January 4, 2021, 5:16pm UTC](https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612/7 "2021-01-04T17:16:56Z")

</div>

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

[https://github.com/discourse/discourse\_api\_docs/pull/25](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](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](https://github.com/discourse/discourse/tree/master/spec/requests/api) by using a tool called [rswag](https://github.com/rswag/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.

---

<div class="post-metadata">

**Author:** ![guidoleenders](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/guidoleenders/32/196268_2.png) [@guidoleenders](https://meta.discourse.org/u/guidoleenders)\
**Post date:** [January 4, 2021, 5:44pm UTC](https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612/8 "2021-01-04T17:44:51Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![blake](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/blake/32/157322_2.png) [@blake](https://meta.discourse.org/u/blake)\
**Post date:** [January 4, 2021, 5:53pm UTC](https://meta.discourse.org/t/validating-openapi-swagger-on-https-docs-discourse-org-openapi-json/169612/9 "2021-01-04T17:53:45Z")

</div>