Referencing files with OpenAPI

[igbluz]

I want to reference another openapi yaml file (problem.yaml) from my master yaml (openapi.yaml)

I use this construct in openapi.yaml:

        '400':
          description: Invalid request data
          content:
            'application/problem+json':
              schema:
                $ref: 'problem.yaml#/components/schemas/BadRequestProblem'

With the openapi generator tool I can generate my stubs correctly.
When I start OpenLiberty server with the command mvn liberty:dev I get these OpenApi Validation exception:

[INFO] [ERROR   ] CWWKO1650E: Validation of the OpenAPI document produced the following error(s): 
[INFO]                                                                                                                
[INFO]  - Message: The "problem.yaml#/components/schemas/BadRequestProblem" value is an invalid reference, Location: #/paths/~1inventory~1systems~1{hostname}/get/responses/400/content/application~1problem+json/schema

Reproduce the error
You can reproduce very easy. Just use the guide-microprofile-openapi sample and copy the problem.yaml to the wepapp/META-INF directory.

Replace the 400: response with this:

        400:
          description: Invalid request data
          content:
            'application/problem+json':
              schema:
                $ref: 'problem.yaml#/components/schemas/BadRequestProblem'

After `mvn clean liberty:dev you can see the error.

Expected behavior
The Server starts without error and shows the OpenAPI UI (http://localhost:9080/openapi/ui) without error.

Diagnostic information:

• OpenLiberty Version: 20.0.0.12
• Java Version:

 openjdk version "1.8.0_265"
OpenJDK Runtime Environment (build 1.8.0_265-b01)
OpenJDK 64-Bit Server VM (build 25.265-b01, mixed mode)

• server.xml: unchanged from the sample

Additional context
I uploaded problem.yaml.txt, just rename it to problem.yaml and use it

problem.yaml.txt

[Emily-Jiang]

@igbluz thanks for raising this issue! After the discussion with MicroProfile Open API group, this behaviour should be speced in the spec. Are you ok to close this as we will continue our discussion in eclipse/microprofile-open-api#463?

[bmarwell]

@Emily-Jiang I think this is now mandatory in OA 3.0: https://swagger.io/docs/specification/using-ref/
See the section "$ref Syntax" which clearly references other files. Today I stumbled upon this not being supported in OL.

Does this still need a discussion?

[igbluz]

Thank you for the responses.
We resolved the case in using the $ref for referencing other files in nexus.

responses:
   ‘200’:
        content:
              application/json:
                    schema:
                         type: array
                         items:
                              $ref: ‘http://myserver.mydomain.com/nexus/repository/openapi/responses/200response’

[bmarwell]

@igbluz could you kindly elaborate what's the current status? Thanks. 🙏🏻