وثائق Discourse openapi.json لا تتبع مواصفات OpenAPI 3.1.0

Kyle-Ye · 19 يونيو 2023، 6:06م

لست متأكدًا مما إذا كان هذا هو أفضل مكان لتقديم مثل هذه الملاحظات، ولكن مستودع Github ذي الصلة أغلق بوابة تقديم المشكلات، لذا أحاول تقديم الملاحظات هنا.
GitHub - discourse/discourse_api_docs: Discourse API Documentation

ملف openapi.json المستضاف على GitHub - discourse/discourse_api_docs: Discourse API Documentation ليس في الواقع ملف openapi صالحًا.

انظر المزيد من المعلومات هنا Discourse openapi.json generate issue · Issue #277 · mattpolzin/OpenAPIKit · GitHub

باختصار

يجب أن يكون مفتاح 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، فمن المحتمل أنهم لم يكلفوا أنفسهم عناء ذكر الكثير من هذه القواعد داخل مواصفات OpenAPI نفسها.

Kyle-Ye · 19 يونيو 2023، 6:15م

يتم إنشاء openapi.json الخاص بـ Discourse بواسطة أداة تسمى rswag

ربما تكون هذه مشكلة في المصدر. وعندما يقوم المصدر بإصلاحها، يجب علينا ترقية إصدار التبعية وتحديث ملفات التوثيق المقابلة.

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 · 3 أبريل 2024، 4:59م

تمت معالجة طلب السحب أعلاه ^ في مرحلة لاحقة هنا:

github.com/discourse/discourse

Fix structural problems with the openapi spec

main ← Kyle-Ye:bugfix/openapi

opened 08:26AM - 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	6	892	4 يناير 2021
Swagger, WADL or similar for the REST API? Dev	10	14660	30 أغسطس 2016
Contributing to the Discourse API documentation Contributing rest-api , how-to	4	3182	2 أبريل 2024
Document basic-info api endpoint Bug rest-api	4	176	6 أبريل 2024
Google Structured Data -- Invalid Article Schema Support	44	8736	9 نوفمبر 2018

وثائق Discourse openapi.json لا تتبع مواصفات OpenAPI 3.1.0

الموضوعات ذات الصلة