swagger-api / swagger-parser

Swagger Spec to Java POJOs
http://swagger.io
Apache License 2.0
780 stars 525 forks source link

resolveFully breaks 3.0 spec for headers via $ref in request and response #2060

Open david0 opened 7 months ago

david0 commented 7 months ago

Given the following files:

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
paths:
  /users/:
    get:
      parameters:
        - $ref: 'headers.yml#/XRequestId'
      responses:
        '200':
          description: Ok
          headers:
            X-Request-Id:
              $ref: 'headers.yml#/XRequestId'

and

XRequestId:
  in: header
  name: X-Request-Id
  schema:
    type: string
  required: false
        OpenAPIV3Parser parser = new OpenAPIV3Parser();
        ParseOptions options = new ParseOptions();
        options.setResolveFully(true);

        var api = parser.read(file, null, options);
        String content = Yaml.pretty(api);

the output will contain a $ref that cannot be resolved:

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
servers:
- url: /
paths:
  /users/:
    get:
      parameters:
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: Ok
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
components:
  parameters:
    XRequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string

I know the in: is not valid for responses, but swagger-ui seems to be fine with it.

Surprisingly using version: 3.1.0 fixes that thing, unfortunately openapi-generator is not yet ready for that...