Kyle-Ye
19 Giugno 2023, 6:06pm
1
Non sono sicuro che questo sia il posto migliore per inviare questo feedback, ma il repository Github pertinente ha chiuso il portale di invio delle Issue, quindi provo a dare un feedback qui.GitHub - discourse/discourse_api_docs: Discourse API Documentation
Il file openapi.json ospitato su GitHub - discourse/discourse_api_docs: Discourse API Documentation non è in realtà un file openapi valido.
Vedi maggiori informazioni qui Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub
TL,DR
La chiave items per uno schema array “DEVE essere uno schema JSON valido” (json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2-1 ) e uno schema JSON “DEVE essere un oggetto o un booleano” (json-schema.org/draft/2020-12/json-schema-core.html#section-4.3-2 ). Poiché questa parte del Documento OpenAPI è governata dalle regole JSON Schema, probabilmente non si preoccupano di menzionare troppe di queste regole all’interno della specifica OpenAPI stessa.
1 Mi Piace
Kyle-Ye
19 Giugno 2023, 6:15pm
2
Il file openapi.json di Discourse è generato da uno strumento chiamato rswag
Forse questo è un problema upstream. E quando upstream lo risolverà, dovremmo aggiornare la versione della dipendenza e aggiornare i file di documentazione corrispondenti.
opened 06:35PM - 19 Jun 23 UTC
closed 08:30AM - 23 Jun 23 UTC
## Describe the bug
[Discourse API Docs](https://github.com/discourse/discour… se_api_docs) use Rswag 2.9.0 to generate the OpneAPI file.
But the generated file is not full satisfy OpenAPI spec.
```
"schema": {
"additionalProperties": false,
"properties": {
"form_template_ids": {
"items": [], ❌
"type": "array"
}
},
"required": []
}
```
> That schema does not look valid to me. 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](https://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](https://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.
## Steps to Test or Reproduce
Please provide an example repo or the steps to reproduce the behavior.
- Clone https://github.com/discourse/discourse and generated the latest docs `rake rswag:specs:swaggerize` (Or use https://github.com/discourse/discourse_api_docs directly)
- The generated openapi.json is not a valid OpenAPI doc and will make https://github.com/mattpolzin/OpenAPIKit throw an error when parsing it.
## Expected behavior
Geneate a valid openapi.json and openapi.yml file.
## Additional context
See full context here https://github.com/mattpolzin/OpenAPIKit/issues/277
## Dependency versions
The version of are you using for:
* Rswag: 2.9.0
* RSpec:
* Rails:
* Ruby:
## Relates to which version of OAS (OpenAPI Specification)
- [x] OAS3.1
2 Mi Piace
blake
3 Aprile 2024, 4:59pm
3
PR sopra ^ è stato in realtà affrontato a valle qui:
main ← Kyle-Ye:bugfix/openapi
opened 08:26AM - 23 Jun 23 UTC
rswag is extremely permissive; way moreso than the actual OAS standard, or JSON … schema!
It will cause a downstream parsing issue which using openapi.json produced by this repo. (Hosted here https://github.com/discourse/discourse_api_docs)
See more info here: https://github.com/mattpolzin/OpenAPIKit/issues/277#issuecomment-1599019608
Historically, we have fixed such problems, but they have not been completely repaired. And such problems may be added again later.
> See history fix: https://github.com/discourse/discourse/pull/16710
> See bug introduce: https://github.com/discourse/discourse/pull/21028
Some follow up needed:
- After this PR is merged. Please trigger a bot to make an update for https://github.com/discourse/discourse_api_docs repo.
- Add some strict OpenAPI spec test in case such permissive syntax show up again in a later commit/PR.
1 Mi Piace
