Kyle-Ye
19 Junio, 2023 18:06
1
No estoy seguro de si este es el mejor lugar para enviar este tipo de comentarios, pero el repositorio de Github correspondiente ha cerrado el portal de envío de problemas, así que intento dar mi opinión aquí.GitHub - discourse/discourse_api_docs: Discourse API Documentation
El archivo openapi.json alojado en GitHub - discourse/discourse_api_docs: Discourse API Documentation en realidad no es un archivo openapi válido.
Ver más información aquí Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub
En resumen
La clave items para un esquema array “debe ser un esquema JSON válido” (json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2-1 ) y un esquema JSON “debe ser un objeto o un booleano” (json-schema.org/draft/2020-12/json-schema-core.html#section-4.3-2 ). Debido a que esta parte del Documento OpenAPI se rige por las reglas del Esquema JSON, es probable que no se molesten en mencionar demasiadas de esas reglas dentro de la propia especificación OpenAPI.
1 me gusta
Kyle-Ye
19 Junio, 2023 18:15
2
El openapi.json de Discourse es generado por una herramienta llamada rswag
Quizás este sea un problema upstream. Y cuando upstream lo solucione, deberíamos actualizar la versión de la dependencia y los archivos de documentación correspondientes.
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 Me gusta
blake
3 Abril, 2024 16:59
3
PR anterior ^ en realidad se abordó río abajo aquí:
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 me gusta
