Why I'm using file based refs, and you should be to.

This is my first post in what is going to be a series of posts on how you can improve your OpenAPI specification.

If you have no idea what OpenAPI is, read about it here.

I have worked with dozens of different companies OpenAPI documents, everything from a few hundred to few hundred thousand lines, and the lesson I have learned time and time again is that organization is key.

Take any API, document that API in enough detail, and the OpenAPI specification will sprawl.

The really amazing thing about OpenAPI is you can use the standardized document to do ALL KINDS of different things, from generate SDKs, to documentation, perform contract testing, and so much more.

A massive, disorganized, and incomplete OpenAPI document can be a nightmare to work with, and is basically useless when you try to do anything with it.

I firmly believe that the best way to organize an OpenAPI document is to use file based refs.

Now thankfully the really nice thing about OpenAPI, is it has a very simple structure. At the root level of the document you only have 7 keys.

That means there is an obvious, and very simple folder structure you can organize your OpenAPI document into.

openapi.yaml
paths/
components/
- schemas/
- responses/
- parameters/

This is the file structure I would recommend, and I’m not alone, Redocly recommends this structure as well, and they have built out commands in their CLI to bundle from, and split to this structure.

The fastest way for you to begin using this folder structure today is to use the bundle command from the Redocly CLI to bundle your current OpenAPI specification into a single file.

redocly bundle ./openapi.yaml -o ./openapi-bundled.yaml

with ./openapi.yaml being the path to your OpenAPI document, and ./openapi-bundled.yaml being the path for the bundled document.

Then use the split command to split that file into the folder structure above.

redocly split ./openapi-bundled.yaml -o ./openapi

Once again with ./openapi-bundled.yaml being the path to the bundled OpenAPI document, and ./openapi being the path to the folder you want to split the document into.

This functionality is great, but it doesn’t cover the level of granularity or user preference that we like to account for in our tooling at Speakeasy.

With that in mind, we are thinking up solutions that we think will solve this problem for everyone, no matter how granular their organizational system is.

Be good people :D