Discourse openapi.json 문서가 OpenAPI 3.1.0 사양을 따르지 않음

Kyle-Ye · 6월 19, 2023, 6:06오후

이런 피드백을 제출하기에 가장 적합한 곳인지 확신은 없지만, 관련 GitHub 저장소의 이슈 제출 포털이 닫혀 있어 이곳에서 피드백을 남깁니다.
GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub

GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub 에 호스팅된 openapi.json 파일은 실제로 유효한 openapi 파일이 아닙니다.

자세한 내용은 이곳에서 확인하세요: Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub

요약

array 스키마의 items 키는 "유효한 JSON Schema여야 합니다"(json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2-1)며, JSON Schema는 "객체 또는 불리언 값이어야 합니다"(json-schema.org/draft/2020-12/json-schema-core.html#section-4.3-2). OpenAPI 문서의 이 부분은 JSON Schema 규칙에 의해 관리되므로, OpenAPI 사양 자체에서는 이러한 규칙 중 일부에 대해 자세히 언급하지 않는 경향이 있습니다.

Kyle-Ye · 6월 19, 2023, 6:15오후

Discourse의 openapi.json은 rswag라는 이름의 도구によって 생성됩니다.

이것은 상류(upstream)의 문제일 수 있습니다. 상류에서 문제를 수정하면, 의존성 버전을 업그레이드하고 해당 문서 파일들을 업데이트해야 합니다.

github.com/rswag/rswag

[BUG] Generated openapi file does not full satisfy the spec

opened 06:35PM - 19 Jun 23 UTC

closed 08:30AM - 23 Jun 23 UTC

Kyle-Ye

## 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

blake · 4월 3, 2024, 4:59오후

위 PR은 실제로 여기에서 하류(downstream)로 처리되었습니다:

github.com/discourse/discourse

Fix structural problems with the openapi spec (#22256)

main ← Kyle-Ye:bugfix/openapi

merged 05:06PM - 23 Jun 23 UTC

Kyle-Ye

+45 -53

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.

글		댓글	조회수
Validating OpenAPI / Swagger on https://docs.discourse.org/openapi.json Bug rest-api	5	1007	1월 4, 2021
Swagger, WADL or similar for the REST API? Development	10	14885	8월 30, 2016
Contributing to the Discourse API documentation Contributing rest-api , how-to	3	3396	11월 16, 2023
Document basic-info api endpoint Bug rest-api	3	286	4월 3, 2024
Google Structured Data -- Invalid Article Schema Product Support	39	9360	7월 31, 2018

Discourse openapi.json 문서가 OpenAPI 3.1.0 사양을 따르지 않음

Related topics