I'm documenting a REST API for our team and decided to use an openapi specification to keep things consistent. The YAML file is getting huge and hard to read, though. Is there a better way to organize it, or do you just split it into multiple files and hope your tooling can handle it?
openapi supports breaking a large spec into several files The trick is a small root document that defines basic info and servers Then you pull in the rest from separate files The result is easier to read and easier to extend as features grow
organize by domain or resource and keep schemas in a components area Then reference those schemas from the path files using openapi references wherever a type is used This keeps every change in one place and reduces duplication
tooling wise you will want a bundler so you can ship a single openapi file to clients Look for a tool that resolves external references and can output a single file for docs and code generation
structure matters Start with a folder for paths and a folder for components and a small index that lists what is in each file Keep naming consistent to avoid chaos
validation helps a lot Use a linter and a spec validator for openapi to catch cross file issues and broken refs before they bite Your CI can run it on every push
quick starter plan for a week Map out two or three domains Then create a root file and two module files for paths and schemas Bundle them and compare to a one file version If it holds up you can add more modules