CODEWITHSUNDEEP
swaggeropenapi
ololo
ololo

Reputation: 2036

Including Multiple File Paths in Open API Doc

I have quite a large API with many wheels turning. Documenting all of these in one giant openapi.yaml file isn't easy for me so I decided to breakdown the docs to separate paths as shown in the screenshot below:

enter image description here

Now in my customer.yaml file I have the following routes:

/customers/new:
/customers/login:
/customers/logout:

And in my partner.yaml file I have the following routes:

/partners/new:
/partners/login:
/partners/logout:

Now I included the above two files into my final index.yaml file as below

paths:
  - $ref: "./paths/partner.yaml"
  - $ref: "./paths/customer.yaml"

But the final generated doc by the swagger-cli is adding the - character before the path references thereby resulting in a malformed unusable document.

How can I resolve this?

Upvotes: 1

Views: 6141

Answers (1)

MikeRalphson
MikeRalphson

Reputation: 2393

paths in OpenAPI is a map, not an array, so you can't use the yaml - syntax.

You need to include the pathItem keys in your top level file, and put the $refs to the relevant file or fragment of a file there.

For example:

paths:
  /foo:
    $ref: "./foo.yaml"
  /bar:
    $ref: "./paths.yaml#/paths/bar"

Upvotes: 1

Related Questions