OpenAPI Refactorer
Break 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.
Installation
Install as a CLI
npm install -g openapi-refactorer
Install as a Node.js Module
npm install openapi-refactorer
Usage
Basic usage:
openapi-refactorer -i spider.yaml -o baby_spiders.yaml
NOTE: existing files will be overwritten
CLI Options
-V, --version output the version number
-i, --input <file> path of the input OpenAPI file.
-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
Example
Input file
petstore.yaml
openapi: 3.0.0info: # (...) 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
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
openapi: 3.0.0info: # (...) 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
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
get: summary: Info for a specific pet operationId: showPetById # (...) responses: default: description: unexpected error content: application/json: schema: $ref: '../../main.yaml#/components/schemas/Error'
Known Issues
- 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.
Contributing
I'm open for ideas to make OpenAPI Refactorer better. Just send a pull request or open an issue (especially it's more involved).
License
MIT © 2019 Alexis Luengas