Break monolithic OpenAPI documents into several files (and put them back together).
npm install openapi-refactorerBreak monolithic OpenAPI (f.k.a. Swagger) documents into several files (and put them back together). The resulting entrypoint is a valid OpenAPI document and still compatible with common tools.
Currently only the paths object is used for refactoring.
``bash`
npm install -g openapi-refactorer
`bash`
npm install openapi-refactorer
Basic usage:
`bash`
openapi-refactorer -i spider.yaml -o baby_spiders.yaml
> NOTE: existing files will be overwritten
`
-V, --version output the version number
-i, --input
-o, --output [file] path of the main output OpenAPI file. Required if --join option is not used. When omitted, output is sent to stdout. Missing directories within the file path will be created. Existing file are promptlessly overwritten.
--join whether to join/bundle the an OpenAPI file tree into one document.
-h, --help output usage information
Input file
petstore.yaml
`yaml`
openapi: 3.0.0
info:
# (...)
paths:
/pets:
get:
summary: List all pets
operationId: listPets
# (...)
responses:
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
post:
summary: Create a pet
operationId: createPets
# (...)
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
# (...)
responses:
default:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
Command
`bash`
openapi-refactorer -i petstore.yaml -o out/main.yaml
Output file structure
`
out/
├ main.yaml
└ paths/
├ pets.yaml
└ pets/
└ {petId}.yaml
Output files
main.yaml
`yaml`
openapi: 3.0.0
info:
# (...)
paths:
/pets:
$ref: 'paths/pets.yaml#'
'/pets/{petId}':
$ref: 'paths/pets/%7BpetId%7D.yaml#'
components:
schemas:
Error:
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
paths/pets.yaml
`yaml`
get:
summary: List all pets
operationId: listPets
# (...)
responses:
default:
description: unexpected error
content:
application/json:
schema:
$ref: "../main.yaml#/components/schemas/Error"
post:
summary: Create a pet
operationId: createPets
# (...)
paths/pets/{petId}.yaml
`yaml``
get:
summary: Info for a specific pet
operationId: showPetById
# (...)
responses:
default:
description: unexpected error
content:
application/json:
schema:
$ref: '../../main.yaml#/components/schemas/Error'
- When joining/bundling: If a reference points to a definition object which itself references directly to another one, the reference is completely resolved. This produces an equivalent document as the original, but not exactly the _same_ document.
I'm open for ideas to make OpenAPI Refactorer better. Just send a pull request or open an issue (especially it's more involved).