Open API specifications can get quite large, especially for providers with upwards of 500 routes or operations.
The challenge is to create standalone documents scoped by a service or path within the parent API specification and include only the components (schemas, responses, etc.) that pertain to operations included in the child document.
When I went looking for library or utility to do this, I couldn’t find one... so I have developed one myself.
It's a simple command (nodejs based but can be run in a bash terminal or from the Windows command line) which requires a few options, including:
- the provider name (e.g.
- a provider version which is a version you set - allowing you to make minor modifications to the output documents (e.g.
- a service discriminator which is a JSONPath expression to identify a service name within each route in the parent file, this is used to assign operations to services in separate documents (e.g.
- an output directory (e.g.
and of course, the openapi spec document you are splitting up.
an example is shown here:
openapi-doc-util split \
-n github \
-v v0.1.0 \
-s '$["x-github"].category' \
-o ./dev \
Help for the command is available using
The net result is 59 self-contained, service scoped documents, containing only the components referenced by routes in the service document.
Splitting up a large open API spec document, is the first stage in developing a StackQL provider which we will discuss next time!