Discourse openapi.json Docs does not follow OpenAPI 3.1.0 spec

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

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

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

TL,DR :point_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- 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

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.


PR above ^ was actually addressed downstream here:

1 Like