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/"
info:
version: "0.0.1"
title: "my API"
tags:
- name: "section1"
description: "Some Section"
- name: "section2"
description: "Some other Section"
paths:
##section 1
/section1/some/path:
$ref: 'paths/section1_some_path.yml'
/section1/some-other-path:
$ref: 'paths/section1_some_other_path.yml'

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

paths/section1_some_path.yml:

post:
tags:
- "section1"
parameters:
...

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

Leave a Reply

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