openapi-format
Advanced tools
Format an OpenAPI document by ordering and filtering fields.
The openapi-format CLI can load an OpenAPI file, sorts the OpenAPI fields by ordering them in a hierarchical order, and can output the file with clean indenting, to either JSON or YAML.
When working on large OpenAPI documents or with multiple team members, the file can be become messy and difficult to compare changes. By sorting it from time to time, the fields are all ordered in a structured manner, which will help you to maintain the file with greater ease.
The filtering is a handy add-on to remove specific elements from the OpenAPI like internal endpoints, beta tags, ... This can be useful in CI/CD pipelines, where the OpenAPI is used as source for other documents like Web documentation, Postman collections, test suites, ...
While possible to install globally, we recommend that you add the openapi-format CLI to the node_modules by using:
$ npm install --save openapi-format
or using yarn...
$ yarn add openapi-format
Note that this will require you to run the openapi-format CLI with npx openapi-format your-openapi-file.yaml or, if
you are using an older versions of npm, ./node_modules/.bin/openapi-format your-openapi-file.yaml.
$ npm install -g openapi-format
To execute the CLI without installing it via npm, use the npx method
$ npx openapi-format your-openapi-file.yaml
openapi-format.js <input-file> -o [ouptut-file] [options]
Arguments:
infile the OpenAPI document, can be either a .json or .yaml file
outfile the output file is optional and be either a .json or .yaml file. Files that end in `.json` will be formatted
as JSON files that end in `.yaml` or `.yml` will be YAML format
Options:
-o, --output Save the formated OpenAPI file as JSON/YAML [path]
--sortFile The file to specify custom OpenAPI fields ordering [path]
--filterFile The file to specify filter setting [path]
--no-sort Don't sort the file [boolean]
--rename Rename the OpenAPI title [string]
--configFile The file with all the format config options [path]
--json Prints the file to stdout as JSON [boolean]
--yaml Prints the file to stdout as YAML [boolean]
--help Show help [boolean]
--verbose Output more details of the filter process [count]
| Parameter | Alias | Description | Input type | Default | Required/Optional |
|---|---|---|---|---|---|
| file | the original OpenAPI file | path to file | required | ||
| --output | -o | save the formatted OpenAPI file as JSON/YAML | path to file | optional | |
| --sortFile | -s | the file to specify custom OpenAPI fields ordering | path to file | defaultSort.json | optional |
| --filterFile | -f | the file to specify filter setting | path to file | optional | |
| --no-sort | don't sort the file | boolean | FALSE | optional | |
| --rename | rename the OpenAPI title | string | optional | ||
| --configFile | -c | the file with all the format config options | path to file | optional | |
| --json | prints the file to stdout as JSON | FALSE | optional | ||
| --yaml | prints the file to stdout as YAML | FALSE | optional | ||
| --verbose | -v, -vv, -vvv | verbosity that can be increased, which will show more output of the process | optional | ||
| --help | h | display help for command | optional |
The default sorting based on the following logic, which is stored in the defaultSort.json file. You can easily modify this by specifying your own ordering per key, which can passed on to the CLI (see below for an example on how to do this).
| Key | Ordered by | OpenAPI reference |
|---|---|---|
| root | - openapi - info - servers - paths - components - tags - x-tagGroups - externalDocs | "OpenAPI Objec" https://swagger.io/specification/#openapi-object |
| get | - operationId - summary - description - parameters - requestBody - responses | "Path Item Object" https://swagger.io/specification/#path-item-object |
| post | - operationId - summary - description - parameters - requestBody - responses | "Path Item Object" https://swagger.io/specification/#path-item-object |
| put | - operationId - summary - description - parameters - requestBody - responses | "Path Item Object" https://swagger.io/specification/#path-item-object |
| patch | - operationId - summary - description - parameters - requestBody - responses | "Path Item Object" https://swagger.io/specification/#path-item-object |
| delete | - operationId - summary - description - parameters - requestBody - responses | "Path Item Object" https://swagger.io/specification/#path-item-object |
| parameters | - name - in - description - required - schema | https://swagger.io/specification/#parameter-object) |
| requestBody | - description - headers - content - links | https://swagger.io/specification/#request-body-object) |
| responses | - description - headers - content - links | https://swagger.io/specification/#responses-object) |
| content | (By alphabet) | https://swagger.io/specification/#responses-object |
| components | - parameters - schemas | https://swagger.io/specification/#components-object |
| schema | - description - type - items - properties - format - example - default | https://swagger.io/specification/#schema-object |
| schemas | - description - type - items - properties - format - example - default | |
| properties | - description - type - items - format - example - default - enum |
By specifying the desired filter values for the available filter keys, the openapi-format CLI will strip out any matching item from the OpenAPI document.
For more complex use-cases, we can advise the excellent https://github.com/Mermade/openapi-filter package, which has really extended options for filtering OpenAPI documents.
| Key | Description | Type | Examples |
|---|---|---|---|
| methods | a list OpenAPI methods. | array | ['get','post','put'] |
| tags | a list OpenAPI tags. | array | ['pet','user'] |
| operationIds | a list OpenAPI operation ID's. | array | ['findPetsByStatus','updatePet'] |
| flags | a list of custom flags | array | ['x-exclude','x-internal'] |
Some more details on the available filter keys:
This will remove all fields and attached fields that match the verbs. In the example below, this would mean that
all get, put, post items would be removed from the OpenAPI document.
openapi: 3.0.0
info:
title: API
version: 1.0.0
paths:
/pets:
get:
summary: Finds Pets by status
put:
summary: Update an existing pet
This will remove all fields and attached fields that match the tags. In the example below, this would mean that all
items with the tags pet or user would be removed from the OpenAPI document.
For example:
openapi: 3.0.0
info:
title: API
version: 1.0.0
paths:
/pets:
put:
tags:
- pet
summary: Update an existing pet
This will remove specific fields and attached fields that match the operation ID's. In the example below, this would
mean that the item with operationID findPetsByStatus would be removed from the OpenAPI document.
For example:
openapi: 3.0.0
info:
title: API
version: 1.0.0
paths:
/pets:
get:
operationId: findPetsByStatus
This will remove all fields and attached fields that match the flags. In the example below, this would mean that all
items with the flag x-exclude would be removed from the OpenAPI document.
For example:
openapi: 3.0.0
info:
title: API
version: 1.0.0
paths:
/pets:
get:
x-exclude: true
$ openapi-format openapi.json openapi-formatted.json
-Format a OpenAPI document with the default sorting and saves it as a new YAML file
$ openapi-format openapi.json openapi.yaml
$ openapi-format openapi.json --json
$ openapi-format openapi.json --yaml
$ openapi-format openapi.json openapi.yaml
example:
$ openapi-format openapi.json openapi-formatted.json --no-sort
Which should keep the OpenAPI fields in the same order. This can be needed, when you only want to do a filtering or rename action.
When you want to strip certain flags, tags, methods, operationID's, you can pass a filterFile which contains the
specific values for the flags, tags, methods, operationID's.
This can be useful to combine with the sorting, to end-up with an order and filtered OpenAPI document.
example:
$ openapi-format openapi.json openapi-formatted.json --filter customFilter.yaml
where the customFilter.yaml would contain a combination of all the elements you want to filter out.
flags:
- x-visibility
flagValues: [ ]
tags: [ ]
operationIds:
- addPet
- findPetsByStatus
During CI/CD pipelines, you might want to create different results of the OpenAPI document. Having the option to rename them, might make it easier to work with the results, so that is why we provide this command option.
$ openapi-format openapi.json openapi.json --rename "OpenAPI Petstore - OpenAPI 3.0"
which results in
{
"openapi": "3.0.2",
"info": {
"title": "Swagger Petstore - OpenAPI 3.0",
{
"openapi": "3.0.2",
"info": {
"title": "Swagger Petstore - OpenAPI 3.0",
All the CLI options can be managed in separate configuration file and passed along the openapi-format command. This will make configuration easier, especially in CI/CD implementations where the configuration can be stored in version control systems.
example:
$ openapi-format openapi.json --configFil openapi-format-options.json
The formatting will happen based on all the options set in the openapi-format-options.json file. All the
available OpenAPI format options can be used in the
config file.
This package is inspired by the @microsoft.azure/format-spec from @fearthecowboy. The original code was not available on Github, with the last update was 3 years ago, so to improve support and extend it we tried to reproduce the original functionality.
The filter capabilities from openapi-format are a light version inspired by the work from @MikeRalphson on
the https://github.com/Mermade/openapi-filter package.
[1.0.0] - 2021-03-15
Initial commit with features
FAQs
Format an OpenAPI document by ordering, formatting and filtering fields.
The npm package openapi-format receives a total of 21,416 weekly downloads. As such, openapi-format popularity was classified as popular.
We found that openapi-format demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.