Kyle-Ye
Junho 19, 2023, 6:06pm
1
Não tenho certeza se este é o melhor lugar para enviar esse feedback, mas o repositório Github relevante fechou o portal de envio de Issues, então tento dar o feedback aqui.GitHub - discourse/discourse_api_docs: Discourse API Documentation
O arquivo openapi.json hospedado em GitHub - discourse/discourse_api_docs: Discourse API Documentation na verdade não é um arquivo openapi válido.
Veja mais informações aqui Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub
TL,DR
A chave items para um esquema array \"deve ser um JSON Schema válido\" (json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2-1 ) e um JSON Schema \"deve ser um objeto ou um booleano\" (json-schema.org/draft/2020-12/json-schema-core.html#section-4.3-2 ). Como esta parte do Documento OpenAPI é regida por regras de JSON Schema, eles provavelmente não se preocupam em mencionar muitas dessas regras dentro da própria especificação OpenAPI.
1 curtida
Kyle-Ye
Junho 19, 2023, 6:15pm
2
O openapi.json do Discourse é gerado por uma ferramenta chamada rswag
Talvez este seja um problema upstream. E quando o upstream o corrigir, devemos atualizar a versão da dependência e os arquivos de documentação correspondentes.
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 curtidas
blake
Abril 3, 2024, 4:59pm
3
PR acima ^ foi, na verdade, abordado posteriormente aqui:
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 curtida
