Support YAML merge keys

[Former user]

I'm trying reduce the amount of copy&paste in my OpenAPI specification and decided to use << YAML Merge Key feature.

It seems to solve my issue perfectly, allowing to reuse a schema with custom description for each use case:

openapi: 3.0.0
info:
  title: "Merge keys sample"
  description: "This is a sample OpenAPI specification with YAML Merge Keys feature used."
  version: snapshot

components:
  schemas:
    SelectionOption: &SelectionOption
      type: object
      required:
        - id
        - label
      properties:
        id:
          type: string
          nullable: false
          description: An internal unique identifier, which should be used for any communication with the backend.
        label:
          type: string
          nullable: false
          description: A human-readable name which should be shown to a user instead of the `id`.
          readOnly: true

paths:
  /foo/bar:
    get:
      summary: Blah blah
      responses:
        200:
          description: Blah blah
          content: 
            application/json:
              schema:
                type: object
                properties:
                  foo:
                    <<: *SelectionOption
                    description: "This is description of `foo` field"
                  bar: 
                    <<: *SelectionOption
                    description: "Here is description of bar field"

‌

It works perfectly and it is handled absolutely correctly by SwaggerUI and SwaggerEditor tools. Unfortunately, when I try to validate my Spring Mock MVC interaction against this specification, I get the following exception:

com.atlassian.oai.validator.OpenApiInteractionValidator$ApiLoadException: Unable to load API spec from provided URL or payload:
    - attribute paths.'/foo/bar'(get).responses.200.content.schema.<< is unexpected

    at com.atlassian.oai.validator.OpenApiInteractionValidator.loadApi(OpenApiInteractionValidator.java:162)
    at com.atlassian.oai.validator.OpenApiInteractionValidator.<init>(OpenApiInteractionValidator.java:130)
    at com.atlassian.oai.validator.OpenApiInteractionValidator.<init>(OpenApiInteractionValidator.java:48)
    at com.atlassian.oai.validator.OpenApiInteractionValidator$Builder.build(OpenApiInteractionValidator.java:461)
    at com.atlassian.oai.validator.mockmvc.OpenApiMatchers.isValid(OpenApiMatchers.java:42)

‌

Apparently, Swagger Request Validator does not support the Merge Key feature of YAML format. Of course, the status of the feature is quite uncertain and it’s not required for YAML parsers to implement it, it seems to be really useful and widely supported (as I mentioned, Swagger toolkit supports it, some CI/CD tools like Concourse also tend to support it).

‌

PS: I'm not sure if this is a bug, so I apologize in advance if I messed the issue Kind up.

[James Navin]

Thanks for raising this.

Internally the swagger parsing is done via https://github.com/swagger-api/swagger-parser. We currently use v2.0.5. If the SwaggerUI etc. handle merge keys correctly then its possible that simply bumping the version of swagger-parser will work (caveat - I haven’t tried that).

You should be able to override the swagger-parser dependency in your project to test it out.

[Former user]

Hi, James. Thanks for the advice.

I tried to switch swagger-parser version to the latest one (v2.0.13), but, the problem persists. I investigated the dependencies of my project and found out that swagger-parser depends on Jackson YAML, which, in turn, does not support neither merge keys nor anchors/references. This is a known issue, still open unfortunately, and it seems that all Java Swagger tools suffer from it.

Anyway, I managed to cope with the problem in my project. As it’s suggested on Stackoverflow, I manually transformed YAML to JSON using SnakeYAML library and passed the resulting JSON to swagger-request-validator.