Splitting Swagger API Documentation yaml files

When documenting your API with Swagger/Swagger-UI, one really cool feature to use is the $ref syntax.

As Swagger documentation files tend to get real large und hard too read, splitting the config across multiple files might be a good idea.
With $ref you could do this quite easily.

For example you could reference a single config file per path like so:

swagger: "2.0"
basePath: "my-api/v1/"
  version: "0.0.1"
  title: "my API"
  - name: "section1"
    description: "Some Section"
  - name: "section2"
    description: "Some other Section"


  ##section 1

    $ref: 'paths/section1_some_path.yml'

    $ref: 'paths/section1_some_other_path.yml'

Then have all actions for this path defined in a dedicated file like this:


  - "section1"

This really helped me managing larger documentation files, which otherwise tend to get quite hard to read.

One Reply to “Splitting Swagger API Documentation yaml files”

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.