[OAS 3.1.0] PathItem supports references in the Components object.

[jmini]

In order to support OpenAPI 3.1.0 (see #333) we need the PathItem to support $ref.

Components Object now has a new entry pathItems, to allow for reusable Path Item Objects to be defined within a valid OpenAPI document.

Reference: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#componentsObject

Example (to be verified):

openapi: 3.1.0
info:
  title: Example specification
  version: "1.0"
servers:
- url: http://localhost:8080/
paths:
  /foo:
    $ref: "#/components/pathItems/StandardStatus"
  /bar:
    $ref: "#/components/pathItems/StandardStatus"
components:
  pathItems:
    StandardStatus:
      get:
        parameters:
        - name: extended
          in: query
          schema:
            type: boolean
        responses:
          200:
            description: OK

To be added:

• The model interface PathItem.java is now extending Reference.
• The model interface Components.java: must manage path items.
• Model TCK tests for new fields
• Model TCK test that ref can be set alongside other fields in PathItem

[Azquelt]

I noticed that @CallbackOperation and the proposed @Webhook represent a map entry where the value is a PathItem, so these annotations could have a ref property added.

Added this to the list in the main comment.

[Azquelt]

Thought about this again and I'm less sure. The mapping from annotations to model objects isn't straightforward.

• @Callback represents one entry in the map inside the Callback object (a pair of callbackUrlExpression and CallbackOperation[])
• @CallbackOperation represents one entry in the map inside the PathItem object (a pair of method and Operation)
• @Webhook represents one entry in the webhooks map, inside the OpenAPI object (a pair of name and CallbackOperation[])

I guess @CallbackOperation[] is the part that maps well onto a PathItem object and since that's an array rather than an object, it can't have a ref property.

You could argue that @Callback could have a ref to a PathItem, but it already has a ref property used to reference a Callback. It could have a new property used to reference a PathItem.

I think a new @Webhook annotation could have a ref.

That would leave us with:

Referencing a callback:

@Path("/myOp")
@Callback(name = "myCallback", ref = "#/components/callbacks/myCallback")
public String myOp() { ... }

Referencing a pathItem from a callback:

@Path("/myOp")
@Callback(name = "myCallback", callbackUrlExpression = "/foobar", pathItemRef = "#/components/pathItems/myPathItem")
public String myOp() { ... }

Referencing a pathItem from a webhook:

@OpenAPIDefinition(webhooks = {
    @Webhook(name = "myWebhook", ref = "#/components/pathItems/myPathItem")
})

[Azquelt]

Second complication: not only is a reference to a Path Item permitted in a Callback, a Webhook and in Components.pathItems, but Path Item itself has a $ref field which can be used alongside any other fields (unlike $ref in a reference object).

There are a few OpenAPI issues related to this:

• Ambiguity between Reference Object and PathItem Object OAI/OpenAPI-Specification#2635
• Did we break 3.2 compatibility by removing the Path Item $ref special case? OAI/OpenAPI-Specification#3734

In the current 3.1 dev branch, using $ref alongside other fields is deprecated but still allowed, so I guess we should allow this, at least in the model API. I've added this to the list in the first comment.