Kyle-Ye
Juin 19, 2023, 6:06
1
Je ne suis pas sûr que ce soit le meilleur endroit pour soumettre ce type de commentaires, mais le dépôt Github pertinent a fermé le portail de soumission des problèmes, j’essaie donc de faire part de mes commentaires ici.GitHub - discourse/discourse_api_docs: Discourse API Documentation
Le fichier openapi.json hébergé sur GitHub - discourse/discourse_api_docs: Discourse API Documentation n’est en fait pas un fichier openapi valide.
Voir plus d’informations ici Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub
TL;DR
La clé items pour un schéma array « doit être un schéma JSON valide » (json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2-1 ) et un schéma JSON « doit être un objet ou un booléen » (json-schema.org/draft/2020-12/json-schema-core.html#section-4.3-2 ). Comme cette partie du document OpenAPI est régie par les règles du schéma JSON, ils ne s’embêtent probablement pas à mentionner trop de ces règles dans la spécification OpenAPI elle-même.
1 « J'aime »
Kyle-Ye
Juin 19, 2023, 6:15
2
Le fichier openapi.json de Discourse est généré par un outil nommé rswag
C’est peut-être un problème en amont. Et lorsque le problème sera résolu en amont, nous devrons mettre à jour la version de la dépendance et mettre à jour les fichiers de documentation correspondants.
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 « J'aime »
blake
Avril 3, 2024, 4:59
3
PR ci-dessus ^ a en fait été traité en aval ici :
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 « J'aime »
