Inclusion of Path Item Objects

[PanosBougas]

Hello Karen, I think I found bug

I have 2 openapi YAML files which are the following:

data/openapi.yaml

openapi: "3.1.0"
info:
  version: "1.0.0"
  title: "Sample API"
  description: Buy or rent spacecrafts
  license:
    name: "Apache 2.0"
    url: "https://blabla.com/mojo/"

paths:
  /spacecrafts/{id}:
    $ref: components/path_items/spacecraft.yaml
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
security:
  - ApiKey: []

data/components/path_items/spacecraft.yaml

 parameters:
  - name: id
    description: The unique identifier of the spacecraft
    in: path
    required: true
    schema:
      description: The unique identifier of a resource
      type: string
      pattern: '^\d+$'
get:
  summary: Read a spacecraft
  operationId: getspacecraftById
  responses:
    "200":
      description: The spacecraft corresponding to the provided `id`
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                description: A human readable error message
                type: string
    404:
      description: No spacecraft found for the provided `spacecraftId`
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                description: A human readable error message
                type: string

When I try to load the app I get the following compilation error

 Cannot load OpenAPI document: '/paths/~1spacecrafts~1{id}/$ref': additional property not permitted
'/paths/~1spacecrafts~1{id}': not all additional properties are valid
'/paths': not all properties are valid
'': not all properties are valid at /opt/perlbrew/perls/perl-5.26.1/lib/site_perl/5.26.1/Mojolicious/Plugin/OpenAPI/Modern.pm line 61.

If the inclusion of a file happens inside a schema for example:

openapi: "3.1.0"
info:
  version: "1.0.0"
  title: "Sample API"
  description: Buy or rent spacecrafts
  license:
    name: "Apache 2.0"
    url: "https://admin.adzuna.co.uk/mojo/"

paths:
  /spacecrafts/{id}:
    parameters:
      - name: id
        description: The unique identifier of the spacecraft
        in: path
        required: true
        schema:
          $ref: components/schemas/id.yaml

there is no compilation error in this case.

Any help will be much appreciated! Again, thanks for your time

[karenetheridge]

You can't put a $ref under /paths/<path name> - it has to be an object.

See https://spec.openapis.org/oas/v3.1.0#paths-object and https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.1/schema.yaml#L204-L211.

[PanosBougas]

Thanks for your reply but perhaps I am missing something.

What I am trying to do is this:

paths:
  /spacecrafts/{id}:
    $ref: components/path_items/spacecraft.yaml

The following is a Path Item Object under the Paths Object and based on the documentation it allows to use a $ref (which makes sense, thus the usage of pathItems components if I understand correctly):

  /spacecrafts/{id}:
    $ref: components/path_items/spacecraft.yaml

I found a similar documentation here at the end of the page. https://redocly.com/docs/openapi-visual-reference/paths/

Based on the documentation of the openapi schema that you sent https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.1/schema.yaml#L204-L211

  paths:
    $comment: https://spec.openapis.org/oas/v3.1.0#paths-object
    type: object
    patternProperties:
      '^/':
        $ref: '#/$defs/path-item'
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

If I translate it correctly, It says that paths is an object which its' properties must match this pattern ^/ in their name and these properties will be Path Items themselves. But it doesn't say anything about references so I guess you are right after all.

I am just trying not to create a big yaml file and I was hoping that I will not have to write the path-items inside the same file.

[PanosBougas]

Perhaps this is what I would like the documentation to say https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.1/schema.yaml#LL248C3-L248C26

I did a little bit of search and it seems that this was discussed last year in the main OpenAPI specification github repo https://github.com/OAI/OpenAPI-Specification/issues/2635#issuecomment-1186016708

[karenetheridge]

Yup, unfortunately it looks like discussion on that has stalled without making any changes.