Specification Document Splitting Clarification

Currently, the Location and formats section of the MP OpenAPI specification reads as follows:

Vendors are required to fetch a single document named openapi with an extension of yml, yaml or json, inside the application module’s root META-INF folder. If there is more than one document found that matches one of these extensions the behavior of which file is chosen is undefined (i.e. each vendor may implement their own logic), which means that application developers should only place a single openapi document into that folder.

Here, the specification states that vendors are only required to retrieve a single document, which contrasts with the OpenAPI specification, which states the following:

An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.

From local tests, it would seem that splitting the OpenAPI document across multiple files, as permitted by the OpenAPI specification, is not supported within MP OpenAPI implementations. If this is the case, the MP OpenAPI specification is a little vague on whether splitting is permitted, as the MP specification states that vendors are only required to fetch a single document:

Vendors are required to fetch a single document named openapi with an extension of yml, yaml or json, inside the application module’s root META-INF folder.

This stems from an issue raised against Open Liberty #https://github.com/OpenLiberty/open-liberty/issues/15428. This was further tested with Open Liberty implementation of 2.0 which consumes SmallRye, which displayed the same behaviour as described in the issue.

If splitting is not supported by MP OpenAPI, I believe we should update the specification to clarify and reflect this.

[msmiths]

@MikeEdgar I am not convinced that we can claim that document splitting is supported as long as the user follows the caveats that you have outlined, i.e., the referenced files are put in an accessible location and absolute references are used. My understanding of what @igbluz is trying to achieve is that the referenced files should be packaged along with the implementation classes, i.e., resource class files and the YAML document contained in the same JAR file. This JAR is then packaged in the relevant WAR and the openapi.yaml includes references to schemas defined by the YAML document embedded in the JAR. I am not an expert on references, but I believe that the intention is that the runtime should be able to resolve the references without needing to make an HTTP request to a file that is really local.

I believe that it is worth putting more thought into this scenario in a future version of the MP OpenAPI specification and providing a clearer definition of what is and is not supported by MP OpenAPI.

[MikeEdgar]

@msmiths - I absolutely agree with you. I think this comes down to defining support for split OpenAPI files and support for generating split files. My earlier comments were intended to help get it working in the current state environment.