How to use multiple references in OpenAPI 3 yaml file's paths section?

Viewed 148

I try to organize my one giant OpenAPI yaml file into several small pieces and then bundle it with swagger-cli. And I run into the paths section.

This is my openapi.yml file now:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  description: Multi-file boilerplate for OpenAPI Specification.
  license:
    name: MIT
servers:
  - url: http://example.swagger.io/v1
paths:
  /blog:
    $ref: './routes/blog/create-getall.yml'
  /blog/{id}:
    $ref: './routes/blog/show-update-delete.yml'

Now the problem is I want to separate create-getall.yml file into create.yml and get-all.yml, and I want to split show-update-delete.yml file into show.yml, update.yml and delete.yml files.

But after I do this split, I try to use files as reference like this:

paths:
  /blog:
    $ref: './routes/blog/create.yml'
    $ref: './routes/blog/get-all.yml'
  /blog/{id}:
    $ref: './routes/blog/with-id.yml'

And I get Map keys must be unique error message.

If I try $ref1, $ref2 and similar, then I get Property $ref1 is not allowed error.

I tried to use allOf, but it leads to Property allOf is not allowed. error.

The create.yml file is this:

post:
  tags:
  - blog
  summary: create a blog post
  description: |
    You can create a new blog post.
  parameters:
  - in: body
    name: content
    schema:
      $ref: 'Post.yml'
  responses:
    200:
      description: new item's ID

So how can I use these splitted files in paths section?

1 Answers

OpenAPI Specification does not have a way to use multiple $refs under a single path. There's an existing feature request to allow $refs on the operation level which, if implemented, would support your scenario.

Related