How to split Swagger (OpenAPI) spec into small files ?
2 min readMay 25, 2021
To manage and collaborate the API documentations of a large project, we follow the below steps
- Write details of each endpoints in a separate yaml files.
- Write each models in separate yaml files so that we can reuse it.
- Combine all the yaml files using `swagger-cli`
- Serve the swagger doc in html format using an express server
You could checkout these example github repository for details.
Write details of each endpoints in a separate yaml files.
In the example we have 2 endpoints `/contact` and `/product`. YAML files are created with below folder structure.
Write each models in separate yaml files so that we can reuse it.
Below image refers the folder structure of defenitions
Following image refers the entry file (index.yaml)
Now combine the yaml files and generate single json file
# swagger-cli bundle swagger/index.yaml --outfile swagger/index.jsonyarn doc:generate
This is the script section of package.json. doc:generate
will generate a sinle json file.
Serve the swagger doc in html format using an express server
Create a route api/docs
using express and server the doc as follows