Kyle-Ye
19. Juni 2023 um 18:06
1
Ich bin mir nicht sicher, ob dies der beste Ort ist, um solches Feedback zu geben, aber das relevante Github-Repository hat das Einreichen von Problemen geschlossen, daher versuche ich, hier Feedback zu geben.GitHub - discourse/discourse_api_docs: Discourse API Documentation
Die openapi.json-Datei unter GitHub - discourse/discourse_api_docs: Discourse API Documentation ist tatsächlich keine gültige OpenAPI-Datei.
Weitere Informationen finden Sie hier: Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub
TL,DR
Der items-Schlüssel für ein array-Schema „MUSS ein gültiges JSON-Schema sein“ (json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2-1 ) und ein JSON-Schema „MUSS ein Objekt oder ein Boolean sein“ (json-schema.org/draft/2020-12/json-schema-core.html#section-4.3-2 ). Da dieser Teil des OpenAPI-Dokuments von JSON-Schema-Regeln gesteuert wird, wird wahrscheinlich nicht viel von diesen Regeln innerhalb der OpenAPI-Spezifikation selbst erwähnt.
1 „Gefällt mir“
Kyle-Ye
19. Juni 2023 um 18:15
2
Discourse’s openapi.json wird von einem Tool namens rswag generiert
Möglicherweise handelt es sich hierbei um ein Upstream-Problem. Und wenn Upstream es behebt, sollten wir die Abhängigkeitsversion aktualisieren und die entsprechenden Dokumentationsdateien aktualisieren.
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 „Gefällt mir“
blake
3. April 2024 um 16:59
3
PR oben ^ wurde tatsächlich hier weiter unten behoben:
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 „Gefällt mir“
