Redocly / redocly-cli

⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more.
https://redocly.com/docs/cli/
MIT License
942 stars 148 forks source link

lint may miss allof #1768

Open alivedise opened 3 months ago

alivedise commented 3 months ago

Describe the bug redocly lint does not consider allOf

Expected behavior redocly lint should be able to merge stuff before linting

Minimal reproducible OpenAPI snippet(if possible) I'd this openapi yaml and when I turn on 'operation-4xx-problem-details-rfc7807' to lint it, it would bring errors about type is missing; however type is defined in Problem and if I use redocly build-docs the type field is correctly generated in the html.

openapi: 3.1.0
info:
  title: CloudEvents API
  version: 1.0.0
  description: API for handling CloudEvents with extended data

servers:
  - url: https://api.alive.dev/v1

security:
  - BearerAuth: []

paths:
  /events/{id}:
    get:
      operationId: getCloudEvent
      summary: Get a CloudEvent by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Single CloudEvent
          headers:
            ETag:
              $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/headers-1.0.0.yaml#/ETag'
          content:
            application/cloudevents+json:
              schema:
                $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/event-1.0.0.yaml#/CloudEvent'
        '404':
          $ref: '#/components/responses/404'

components:
  responses:
    '404':
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFound'
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: >
            A URI reference that uniquely identifies the problem type in the context of the provided API.
          default: 'about:blank'
          example: '/some/uri-reference'
        title:
          type: string
          description: >
            A short summary of the problem type. Written in English and readable for engineers, 
            usually not suited for non-technical stakeholders and not localized.
          example: some title for the error situation
        status:
          type: integer
          format: int32
          description: >
            The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: 600
        detail:
          type: string
          description: >
            A human-readable explanation specific to this occurrence of the problem, helping to 
            pinpoint the problem and providing advice on how to proceed. Written in English and 
            readable for engineers, usually not suited for non-technical stakeholders and not localized.
          example: some description for the error situation
        instance:
          type: string
          format: uri-reference
          description: >
            A URI reference that identifies the specific occurrence of the problem, e.g. by adding 
            a fragment identifier or sub-path to the problem type. May be used to locate the root 
            cause of this problem occurrence in the source code.
          example: '/some/uri-reference#specific-occurrence-context'
      required:
        - type
        - title
        - status
    NotFound:
      allOf:
        - $ref: '#/components/schemas/Problem'
        - properties:
            status:
              type: integer
              example: 404
            title:
              type: string
              example: "Not Found"
            detail:
              type: string
              example: "The requested resource could not be found but may be available in the future."

Screenshots The correctly generated html with type field.

截圖 2024-08-07 晚上7 33 08

Additional context error message

api-doc [main●●] % redocly lint openapi-single.yaml
(node:43315) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
validating openapi-single.yaml...
[1] openapi-single.yaml:98:11 at #/components/schemas/NotFound/allOf/1/properties/type

SchemaProperties object should contain `type` field.

 96 | allOf:
 97 |   - $ref: '#/components/schemas/Problem'
 98 |   - properties:
 99 |       status:
100 |         type: integer

Error was generated by the operation-4xx-problem-details-rfc7807 rule.
jeremyfiel commented 2 months ago

should be able to merge stuff

This is not valid behavior for JSON Schema, which is the validation language used for OpenAPI.

Each subschema in an allOf is validated independently and cannot "see into" or "merge" other schemas. The validation here is correctly providing a warning per the JSON Schema specification.


The reason you see the output on the html version is because all schemas have been resolved and the final output is compiled.