eclipse-vertx / eclipse-vertx/vertx-openapi

$ref to Common OpenAPI Subset Files

Open
#91 2 comments 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
Java
Stars
15
Forks
19
PR merge metrics
No merged PRs in 30d

Description

#### Read me

Read this first before creating an issue:

- do not use this issue tracker to ask questions, instead use one of these [channels](https://vertx.io/community/). 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 ?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.