Discourse openapi.json Docs does not follow OpenAPI 3.1.0 spec

Contribute Bug

AI-generated summary

Kyle-Ye reports that Discourse’s openapi.json file does not comply with OpenAPI 3.1.0 spec due to invalid use of the items key in array schemas, which must reference a valid JSON Schema (object or boolean) per JSON Schema 2020-12. The file is generated by rswag, and Kyle-Ye suggests this may be an upstream issue, referencing rswag#647. blake notes that the issue was addressed downstream in Discourse via PR #22256, implying the fix may already be implemented or in progress. This is categorized as a bug under the rest-api tag.

1

I’m not sure if this is the best place to submit such feedback, but the relevant Github repository has closed the Issue submission portal, so I try to give feedback here.
GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub

The openapi.json file hosted at GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub is actually not a valid openapi file.

See more info here Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub

TL,DR :backhand_index_pointing_down:

The items key for an array schema "MUST be a valid JSON Schema" (json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2-1) and a JSON Schema "MUST be an object or a boolean" (json-schema.org/draft/2020-12/json-schema-core.html#section-4.3-2). Because this part of the OpenAPI Document is governed by JSON Schema rules, they likely don’t bother mentioning too many of those rules inside the OpenAPI specification itself.

1 Like
2

Discourse’s openapi.json is generated by a tool named rswag

Maybe this is an upstream issue. And when upstream fix it, we should upgrade the dependency version and update the corresponding doc files.

https://github.com/rswag/rswag/issues/647

2 Likes
3

PR above ^ was actually addressed downstream here:

https://github.com/discourse/discourse/pull/22256

1 Like