Kyle-Ye
19.Июнь.2023 18:06:04
1
Не уверен, что это лучшее место для такой обратной связи, но в соответствующем репозитории GitHub закрыт портал для создания задач (Issues), поэтому я пытаюсь оставить отзыв здесь.GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub
Файл openapi.json, размещённый по адресу GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub , на самом деле не является валидным файлом OpenAPI.
Подробнее см. здесь: Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub
TL;DR
Ключ items для схемы array «ДОЛЖЕН быть валидной схемой JSON» (json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2-1 ), а схема JSON «ДОЛЖНА быть объектом или булевым значением» (json-schema.org/draft/2020-12/json-schema-core.html#section-4.3-2 ). Поскольку эта часть документа OpenAPI регулируется правилами JSON Schema, в самой спецификации OpenAPI, вероятно, не стоит упоминать слишком многие из этих правил.
1 лайк
Kyle-Ye
19.Июнь.2023 18:15:01
2
Файл openapi.json для Discourse генерируется утилитой под названием rswag
Возможно, это проблема на стороне исходного проекта. Когда она будет исправлена, мы должны обновить версию зависимости и соответствующие файлы документации.
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 лайка
blake
03.Апрель.2024 16:59:13
3
PR выше ^ был фактически устранён ниже по потоку здесь:
main ← Kyle-Ye:bugfix/openapi
merged 05:06PM - 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 лайк
