OpenAPI/AsyncAPI detection matches `"openapi":`/`asyncapi:` keys inside JSON Schemas that describe OpenAPI documents, and redocly.yaml's theme section

Đang mở
  • Có gì không ổn?
#272 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
Nửa ngày
Mức phù hợp với người mới
65/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
openapi, python
Lĩnh vực
devtools

Hướng nghiên cứu

The detection regex is at project_validator/ecosystems/openapi.py line 50, and REDOCLY_SETTINGS is near line 170 of the same file. Start by reading how the OpenAPI profile chooses which files to scan, then run the repro from the issue (a JSON Schema with a nested openapi property, and a redocly.yaml with a top-level openapi: key). Done means both files are no longer treated as API descriptions, and real openapi.yaml files still pass.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

^\s{0,4}"(?:openapi|swagger)": matches a property key in SchemaStore's openapi-3.X.json, asyncapi's definitions/*/asyncapi.json and OAI's _archive_/schemas/v2.0/schema.json (JSON Schemas about OpenAPI), so schema repositories are judged as API-description projects and FAIL schema-declared ("5 OpenAPI files do not declare their version"); Redocly's redocly.yaml has a top-level openapi: theme section and FAILs "no info.version". An OpenAPI document has openapi: "3.x" as a string value (or swagger: "2.0") and info:; a schema has $schema/type/properties.

Evidence from the corpus audit

SchemaStore/schemastore, asyncapi/spec-json-schemas, OAI/OpenAPI-Specification / schema-declared (and detection)
  • kind: FALSE_POSITIVE
  • actual: FAIL: OpenAPI/AsyncAPI: 5 OpenAPI files do not declare their version (openapi) and info.version
    (SchemaStore); OpenAPI/AsyncAPI: 14 AsyncAPI files do not declare their version (asyncapi) and info.version
    (spec-json-schemas); OpenAPI/AsyncAPI: 1 OpenAPI file does not declare its version … _archive_/schemas/v2.0/schema.json: no openapi (OAI)
  • expected: the files are JSON Schemas that describe OpenAPI/AsyncAPI documents (or a Kustomization), not
    descriptions; they should not be found by the OpenAPI/AsyncAPI profile at all, and SchemaStore and
    spec-json-schemas should not be "OpenAPI/AsyncAPI" projects (which also yields their static-analysis,
    schema-validation, schema-compatibility and schema-examples OpenAPI FAIL/WARN lines).
  • evidence: project_validator/ecosystems/openapi.py:50:
    OPENAPI: re.compile(r"^(?:openapi|swagger)\s*:|^\s{0,4}\"(?:openapi|swagger)\"\s*:", re.MULTILINE) matches a
    property key indented by 4 spaces inside "properties" or "required".
    SchemaStore src/schemas/json/openapi-3.X.json:2: "$schema": "https://json-schema.org/draft/2020-12/schema",
    and :8: "openapi": {; src/schemas/json/grpc-api-gateway.json:9: "openapi": {;
    src/test/kustomization/openapi.json:4: "openapi": { (a Kustomization).
    spec-json-schemas definitions/1.0.0/asyncapi.json:3: "$schema": "http://json-schema.org/draft-04/schema#",
    and :18: "asyncapi": {.
    OAI _archive_/schemas/v2.0/schema.json:3: "$schema": "http://json-schema.org/draft-04/schema#", and :18:
    "swagger": {.
  • repro: a file openapi-schema.json with {"$schema": "https://json-schema.org/draft/2020-12/schema", "properties": {\n "openapi": {"type": "string"}}}; the project is detected as OpenAPI and the file fails
    schema-declared with "no openapi" and "no info.version". A fix is to require the key at the top level (parse the
    head, or at most 2 spaces of indentation and not inside properties), or to exclude files that are JSON Schemas.
  • confidence: high
Redocly/openapi-starter / schema-declared
  • kind: FALSE_POSITIVE
  • actual: FAIL: 1 OpenAPI file does not declare its version (openapi) and info.version / redocly.yaml: no info.version
  • expected: PASS: redocly.yaml is the Redocly CLI configuration; its top-level openapi: key is Redocly's
    documentation-theme section, not a specification version. The one real description, openapi/openapi.yaml,
    declares both.
  • evidence: redocly.yaml:1: # See https://redocly.com/docs/cli/configuration/ for more information.;
    redocly.yaml:2-4: apis: / sample@v1: / root: openapi/openapi.yaml; redocly.yaml:11: openapi:;
    openapi/openapi.yaml:1: openapi: 3.1.0, :7: version: 1.0.0. The same regex as above
    (project_validator/ecosystems/openapi.py:50) matches openapi: at column 0 regardless of its value.
  • repro: redocly.yaml with apis: {a: {root: openapi.yaml}}\nopenapi:\n codeSamples: {} next to a valid
    openapi.yaml. A fix is to exclude the known Redocly config names (REDOCLY_SETTINGS already lists them,
    openapi.py:170) and/or require the key's value to look like a version (openapi: 3.x, swagger: "2.0").
  • confidence: high

Found by the regression-corpus audit (235 real repositories, one or more per ecosystem profile; corpus and expected results in corpus/). Evidence is quoted from the audited checkouts at the commits pinned in corpus/projects.toml; <checkouts>/<owner>__<repo> is such a checkout.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ByTXNqDWdM7HzezrFtEvQt

Ngôn ngữ chính
Python
Star
4
Fork
1
Merge trung bình
10 giờ 41 phút
Pull request đã merge (30 ngày)
79

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của cpp-best-practices/project_validator

Tất cả issue của cpp-best-practices/project_validator

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.