$ref to Common OpenAPI Subset Files

[jawaff]

Read me

Read this first before creating an issue:

• do not use this issue tracker to ask questions, instead use one of these channels. Questions will likely be closed without notice.
• you shall create a feature request only when it is general purpose enough.
• make sure that the feature is not already

Describe the feature

In the previous vertx openapi/json schema solution it was possible to make a $ref to a file that contained a common piece of OpenAPI information that is reused by multiple OpenAPI files. For example, a TotalCount header or a limit query parameter could be defined in a common file. The one big detail about these files is that they are not valid according to the json schema spec because they might look something like this:

name: limit
in: query
required: false
description: The limit for the returned page
schema:
  type: integer
  format: int32
  minimum: 0

Use cases

When I was updating to the newish openapi/json schema solution in Vertx I passed these common openapi files into the additionalContractFiles argument for OpenAPIContract::from. Of course these files failed the validation for obvious reasons, but I bring it up because it's a loss in functionality between the old and new solution.

Maybe this is as simple as adding another additionalContractFiles argument that is for referenced files that follow the OpenAPI spec. Haven't looked into it that far, but it would be a nice to have feature for sure.

Contribution

Who should implement this feature ? are you volunteering for implementing this feature or
do you know that is able and willing implement this feature ?

[jawaff]

The old solution I'm referring to is the vertx-web-openapi module in the vertx-web project. As far as I know, this is the replacement since that module was removed from that repository a while ago, which I interpret as it being deprecated.

[pk-work]

Hi, so you can't put this files into your SchemaRepository via the from method. Maybe this answer helps you. Passing your own SchemaRepository, will avoid these checks.

Another option is making your files compliant by adding a OpenAPI header [1].

Does this solve your issue?

[1] https://github.com/eclipse-vertx/vertx-openapi/blob/main/src/test/resources/io/vertx/tests/contract/from_with_path_and_additional_files/components.yaml