{"id":14986706,"url":"https://github.com/thim81/openapi-format","last_synced_at":"2025-05-16T00:03:37.491Z","repository":{"id":37407792,"uuid":"345077537","full_name":"thim81/openapi-format","owner":"thim81","description":"Format an OpenAPI document by ordering, formatting and filtering fields.","archived":false,"fork":false,"pushed_at":"2025-05-02T09:14:30.000Z","size":2164,"stargazers_count":118,"open_issues_count":11,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-02T09:49:30.050Z","etag":null,"topics":["cli","converting","filtering","formatting","oas","openapi","openapi-fields","openapi-overlay","openapi-tooling","openapi-tools","sorting","swagger"],"latest_commit_sha":null,"homepage":"https://openapi-format-playground.vercel.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thim81.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-06T11:31:52.000Z","updated_at":"2025-05-02T09:14:34.000Z","dependencies_parsed_at":"2023-01-23T20:15:20.148Z","dependency_job_id":"cd90a033-77b8-48ec-a15e-ccd78b86f83b","html_url":"https://github.com/thim81/openapi-format","commit_stats":{"total_commits":306,"total_committers":15,"mean_commits":20.4,"dds":0.5032679738562091,"last_synced_commit":"fcafeb7e04b0738bafdc283c7db3cac79efc3c4c"},"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thim81%2Fopenapi-format","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thim81%2Fopenapi-format/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thim81%2Fopenapi-format/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thim81%2Fopenapi-format/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thim81","download_url":"https://codeload.github.com/thim81/openapi-format/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254442854,"owners_count":22071877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","converting","filtering","formatting","oas","openapi","openapi-fields","openapi-overlay","openapi-tooling","openapi-tools","sorting","swagger"],"created_at":"2024-09-24T14:13:23.215Z","updated_at":"2025-05-16T00:03:32.448Z","avatar_url":"https://github.com/thim81.png","language":"JavaScript","readme":"![openapi-format icon](./assets/openapi-format-logo.svg)\n\n\u003ca href=\"https://www.npmjs.com/package/openapi-format\" alt=\"Latest Stable Version\"\u003e![npm](https://img.shields.io/npm/v/openapi-format.svg)\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/openapi-format\" alt=\"Total Downloads\"\u003e![npm](https://img.shields.io/npm/dw/openapi-format.svg)\u003c/a\u003e\n\n# openapi-format\n\nFormat an OpenAPI document by ordering, formatting, filtering, and applying overlays to OpenAPI documents.\n\nThe openapi-format CLI can sort the OpenAPI fields by ordering them in a hierarchical order, format the casing of the fields and\noutput cleanly indented JSON or YAML.\n\nAdditional features include powerful filtering options based on flags, tags, methods, operationIDs, and even unused components.\nTo quickly standardize OpenAPI documents there is support for generating the operationIds and apply casing rules for consistency.\n\nThe CLI can split large OpenAPI documents into modular, multi-file structures for easier management. \nFor upgrades, the openapi-format CLI offers the option to convert an OpenAPI 3.0 document to OpenAPI 3.1.\n\nWith the newly added OpenAPI Overlay support, users can overlay changes onto existing OpenAPI documents, to extend and customize the OpenAPI document.\n\n## Table of content\n* [Use-cases](#use-cases)\n* [Features](#features)\n* [Online playground](#online-playground)\n* [Installation](#installation)\n    + [Local Installation (recommended)](#local-installation-recommended)\n    + [Global Installation](#global-installation)\n    + [NPX usage](#npx-usage)\n* [Command Line Interface](#command-line-interface)\n* [OpenAPI format CLI options](#openapi-format-cli-options)\n* [OpenAPI sort configuration options](#openapi-sort-configuration-options)\n* [OpenAPI formatting configuration options](#openapi-formatting-configuration-options)\n* [OpenAPI filter options](#openapi-filter-options)\n* [OpenAPI generate elements](#openapi-generate-options)\n* [CLI sort usage](#cli-sort-usage)\n* [CLI filter usage](#cli-filter-usage)\n* [CLI OpenAPI overlay usage](#cli-openapi-overlay-usage)\n* [CLI generate usage](#cli-generate-usage)\n* [CLI casing usage](#cli-casing-usage)\n* [CLI split \u0026 bundle usage](#cli-bundle--split-usage)\n* [CLI rename usage](#cli-rename-usage)\n* [CLI convertTo usage](#cli-convertto-usage)\n* [CLI configuration usage](#cli-configuration-usage)\n* [Credits](#credits)\n\n## Use-cases\n\n**Public documentation:**\nAn OpenAPI document is a specification that evolves and changes. To facilitate working with the specification and publishing the\ndocument as public documentation, you want to deliver a clean and structured specification. OpenAPI-format helps you to\norganize the fields by sorting, formatting and filtering specific elements from the OpenAPI like internal endpoints, beta tags, ...\nand even unused schemas, examples, responses, ... with a clean and optimized OpenAPI document as a result.\n\n**Maintenance:**\nWhen working on large OpenAPI documents or with multiple team members, the file can be become messy and difficult to\ncompare changes. By sorting \u0026 formatting from time to time, the fields are all ordered in a structured manner \u0026 properly cased, which will help you\nto maintain the file with greater ease.\n\n**CI/CD pipelines:**\nOpenAPI-format can be useful in CI/CD pipelines, where the OpenAPI is used as the source for other documents like Web documentation,\nPostman collections, test suites, ...\n\n## Features\n\n- [x] Order OpenAPI fields in a default order\n- [x] Order OpenAPI fields in a custom order\n- [x] Order Components elements by alphabet\n- [x] Format the casing (camelCase,PascalCase, ...) of component elements\n- [x] Filter OpenAPI files based on methods\n- [x] Filter OpenAPI files based on flags\n- [x] Filter OpenAPI files based on flags values\n- [x] Filter OpenAPI files based on tags\n- [x] Filter OpenAPI files based on operationID's\n- [x] Filter OpenAPI files based on operations definition\n- [x] Filter OpenAPI files based on response content-types\n- [x] Apply OpenAPI overlay actions\n- [x] Strip flags from OpenAPI files\n- [x] Strip unused components from OpenAPI files\n- [x] Generate OpenAPI elements for consistency\n- [x] Bundle local and remote references in the OpenAPI document\n- [x] Split the OpenAPI document into a multi-file structure\n- [x] Convert OpenAPI 3.0 documents to OpenAPI 3.1 \n- [x] Rename the OpenAPI title\n- [x] Support OpenAPI documents in JSON format\n- [x] Support OpenAPI documents in YAML format\n- [x] Format via CLI\n- [x] Format via local or remote config files\n- [x] Use as a Module\n- [x] Aligned YAML parsing style with Stoplight Studio style\n- [x] Support for OpenAPI 3.0\n- [x] Support for OpenAPI 3.1 (beta)\n- [x] Online playground (https://openapi-format-playground.vercel.app/)\n\n## Online playground\n\nThe [OpenAPI-Format Playground](https://openapi-format-playground.vercel.app/) is a web-based tool for formatting and sorting OpenAPI documents, powered by the openapi-format CLI.\n\n\u003ca href=\"https://openapi-format-playground.vercel.app/\" target=\"_blank\" title=\"OpenAPI-format Playground\" rel=\"nofollow\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/thim81/openapi-format/main/assets/openapi-format-playground.png\" alt=\"OpenAPI-format Playground\" width=\"50%\"\u003e\u003cbr\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/thim81/openapi-format/main/assets/openapi-format-playground-diff.png\" alt=\"OpenAPI-format Playground Diff viewer\" width=\"25%\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/thim81/openapi-format/main/assets/openapi-format-playground-filter.png\" alt=\"OpenAPI-format Playground Filter UI\" width=\"25%\"\u003e\n\u003c/a\u003e\n\nMore info about the features and usage, can be found in the [readme](https://github.com/thim81/openapi-format-playground?tab=readme-ov-file#features).\n\n## Installation\n\n### Local Installation (recommended)\n\nWhile possible to install globally, we recommend that you add the openapi-format CLI to the `node_modules` by using:\n\n```shell\n$ npm install --save openapi-format\n```\n\nor using yarn...\n\n```shell\n$ yarn add openapi-format\n```\n\nNote that this will require you to run the openapi-format CLI with `npx openapi-format your-openapi-file.yaml` or, if\nyou are using an older versions of npm, `./node_modules/.bin/openapi-format your-openapi-file.yaml`.\n\n### Global Installation\n\n```shell\n$ npm install -g openapi-format\n```\n\n### NPX usage\n\nTo execute the CLI without installing it via npm, use the npx method\n\n```shell\n$ npx openapi-format your-openapi-file.yaml\n```\n\n## Command Line Interface\n\n```\nopenapi-format.js \u003cinput-file\u003e -o [output-file] [options]\n\nArguments:\n  input-file   the OpenAPI document can be a local or remote file in JSON or YAML format\n  output-file  the output file is optional and can be either a .json or .yaml file. \n\nOptions:\n\n  --output, -o          Save the formated OpenAPI file as JSON/YAML             [path]\n\n  --sortFile            The file to specify custom OpenAPI fields ordering      [path]\n  --casingFile          The file to specify casing rules                        [path]\n  --generateFile        The file to specify generate rules                      [path]  \n  --filterFile          The file to specify filter rules                        [path]\n  --overlayFile         The file to specify OpenAPI overlay actions             [path]\n\n  --no-sort             Don't sort the OpenAPI file                          [boolean]\n  --keepComments        Don't remove the comments from the OpenAPI YAML file [boolean]\n  --sortComponentsFile  The file with components to sort alphabetically         [path]\n\n  --no-bundle           Don't bundle the local and remote $ref               [boolean]\n  --split               Split OpenAPI document into a multi-file structure   [boolean]\n  \n  --rename              Rename the OpenAPI title                              [string]\n  \n  --convertTo           convert the OpenAPI document to OpenAPI version 3.1   [string]\n\n  --configFile          The file with the OpenAPI-format CLI options            [path]\n\n  --lineWidth           Max line width of YAML output                         [number]\n\n  --json                Prints the file to stdout as JSON                    [boolean]\n  --yaml                Prints the file to stdout as YAML                    [boolean]\n\n  --playground, -p      Open config in online playground\n  --help                Show help                                            [boolean]\n  --version             Output the version number                            \n  --verbose             Output more details of the filter process              [count]\n```\n\n## OpenAPI format CLI options\n\n| Parameter            | Alias         | Description                                                                 | Input type   | Default                    | Info     |\n|----------------------|---------------|-----------------------------------------------------------------------------|--------------|----------------------------|----------|\n| file                 |               | the OpenAPI document can be a local or remote file in JSON or YAML format   | path to file |                            | required |\n| --output             | -o            | save the formatted OpenAPI file as JSON/YAML                                | path to file |                            | optional |\n| --sortFile           | -s            | the file to specify custom OpenAPI fields ordering                          | path to file | defaultSort.json           | optional |\n| --filterFile         | -f            | the file to specify filter setting                                          | path to file | defaultFilter.json         | optional |\n| --casingFile         | -k            | the file to specify casing setting                                          | path to file |                            | optional |\n| --generateFile       | -g            | the file to specify generate rules                                          | path to file |                            | optional |\n| --overlayFile        | -l            | the file to specify OpenAPI overlay actions                                 | path to file |                            | optional |\n| --no-sort            |               | don't sort the OpenAPI file                                                 | boolean      | FALSE                      | optional |\n| --keepComments       |               | don't remove the comments from the OpenAPI YAML file                        | boolean      | FALSE                      | optional |\n| --sortComponentsFile |               | sort the items of the components (schemas, parameters, ...) by alphabet     | path to file | defaultSortComponents.json | optional |\n| --no-bunlde          |               | don't bundle the local and remote $ref in the OpenAPI document              | boolean      | FALSE                      | optional |\n| --split              |               | split the OpenAPI document into a multi-file structure                      | boolean      | FALSE                      | optional |\n| --rename             |               | rename the OpenAPI title                                                    | string       |                            | optional |\n| --convertTo          |               | convert the OpenAPI document to OpenAPI version 3.1                         | string       |                            | optional |\n| --configFile         | -c            | the file with all the format config options                                 | path to file |                            | optional |\n| --lineWidth          |               | max line width of YAML output                                               | number       | -1 (Infinity)              | optional |\n| --json               |               | prints the file to stdout as JSON                                           |              | FALSE                      | optional |\n| --yaml               |               | prints the file to stdout as YAML                                           |              | FALSE                      | optional |\n| --playground         | -p            | open config in online playground                                            |              |                            | optional |\n| --version            |               | output the version number                                                   |              |                            | optional |\n| --verbose            | -v, -vv, -vvv | verbosity that can be increased, which will show more output of the process |              |                            | optional |\n| --help               | h             | display help for command                                                    |              |                            | optional |\n\n## OpenAPI sort configuration options\n\nThe CLI will sort the OpenAPI document in the defined order liked defined per OpenAPI key/field/property/element. The fields that are\nnot specified will keep their order like it is in the original OpenAPI document, so only defined fields will be\nre-ordered.\n\nThe default sorting of the different fields based on the defined order (listed in the table below), which is stored in\nthe [defaultSort.json](https://github.com/thim81/openapi-format/blob/main/defaultSort.json) file.\n\n### OpenAPI sort fields\n\nYou can easily modify this by specifying your own ordering per key, which can be passed on to the CLI (see below for an\nexample on how to do this).\n\n| Key         | Ordered by                                                                                                      | OpenAPI reference                                                         |\n| ----------- | ----------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------------------- |\n| root        | - openapi\u003cbr\u003e\\- info\u003cbr\u003e\\- servers\u003cbr\u003e\\- paths\u003cbr\u003e\\- components\u003cbr\u003e\\- tags\u003cbr\u003e\\- x-tagGroups\u003cbr\u003e\\- externalDocs | [openapi-object](https://spec.openapis.org/oas/v3.0.3.html#openapi-object)                  |\n| get         | - operationId\u003cbr\u003e\\- summary\u003cbr\u003e\\- description\u003cbr\u003e\\- parameters\u003cbr\u003e\\- requestBody\u003cbr\u003e\\- responses                | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject)                |\n| post        | - operationId\u003cbr\u003e\\- summary\u003cbr\u003e\\- description\u003cbr\u003e\\- parameters\u003cbr\u003e\\- requestBody\u003cbr\u003e\\- responses                | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject)                 |\n| put         | - operationId\u003cbr\u003e\\- summary\u003cbr\u003e\\- description\u003cbr\u003e\\- parameters\u003cbr\u003e\\- requestBody\u003cbr\u003e\\- responses                | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject)                 |\n| patch       | - operationId\u003cbr\u003e\\- summary\u003cbr\u003e\\- description\u003cbr\u003e\\- parameters\u003cbr\u003e\\- requestBody\u003cbr\u003e\\- responses                | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject)                 |\n| delete      | - operationId\u003cbr\u003e\\- summary\u003cbr\u003e\\- description\u003cbr\u003e\\- parameters\u003cbr\u003e\\- requestBody\u003cbr\u003e\\- responses                | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject)                 |\n| parameters  | - name\u003cbr\u003e\\- in\u003cbr\u003e\\- description\u003cbr\u003e\\- required\u003cbr\u003e\\- schema                                                   | [parameterObject](https://spec.openapis.org/oas/v3.0.3.html#parameterObject)                 |\n| requestBody | - description\u003cbr\u003e\\- headers\u003cbr\u003e\\- content\u003cbr\u003e\\- links                                                           | [request-body-object](https://spec.openapis.org/oas/v3.0.3.html#request-body-object)             |\n| responses   | - description\u003cbr\u003e\\- headers\u003cbr\u003e\\- content\u003cbr\u003e\\- links                                                           | [responses-object](https://spec.openapis.org/oas/v3.0.3.html#responses-object)                |\n| content     | (By alphabet)                                                                                                   | [responses-object](https://spec.openapis.org/oas/v3.0.3.html#responses-object)                |\n| components  | - parameters\u003cbr\u003e\\- schemas                                                                                      | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object)               |\n| schema      | - description\u003cbr\u003e\\- type\u003cbr\u003e\\- items\u003cbr\u003e\\- properties\u003cbr\u003e\\- format\u003cbr\u003e\\- example\u003cbr\u003e\\- default                  | [schemaObject](https://spec.openapis.org/oas/v3.0.3.html#schemaObject)                    |\n| schemas     | - description\u003cbr\u003e\\- type\u003cbr\u003e\\- items\u003cbr\u003e\\- properties\u003cbr\u003e\\- format\u003cbr\u003e\\- example\u003cbr\u003e\\- default                  |                                                                           |\n| properties  | - description\u003cbr\u003e\\- type\u003cbr\u003e\\- items\u003cbr\u003e\\- format\u003cbr\u003e\\- example\u003cbr\u003e\\- default\u003cbr\u003e\\- enum                        |                                                                           |\n\nHave a look at the folder [yaml-default](test/yaml-default) and compare the \"output.yaml\" (sorted document) with the \"input.yaml\" (original document), to see how openapi-format have sorted the OpenAPI document.\n\n### OpenAPI sort Paths\n\nYou can change the order of the paths defined in the OpenAPI specification and sort them alphabetically (`path`) or by the first tag of the first method (`tags`).\n\nOptions to sort by:\n\n- `original` (default): keep the order as defined in the OpenAPI specification\n- `path`: order the paths alphabetically by the path parts\n- `tags`: order by the first tag of the first method\n\n| Key         | Options                      | OpenAPI reference                                                      |\n|-------------|------------------------------|------------------------------------------------------------------------|\n| sortPathsBy | 'original' / 'path' / 'tags' | [paths-object](https://spec.openapis.org/oas/v3.0.3.html#paths-object) |\n\n\n\n## OpenAPI filter options\n\nBy specifying the desired filter values for the available filter types, the openapi-format CLI will strip out any\nmatching item from the OpenAPI document. You can combine multiple types to filter out a range of OpenAPI items.\n\n| Type                   | Description                                 | Type    | Examples                                  |\n|------------------------|---------------------------------------------|---------|-------------------------------------------|\n| methods                | OpenAPI methods.                            | array   | ['get','post','put']                      |\n| inverseMethods         | OpenAPI methods that will be kept           | array   | ['get','post','put']                      |\n| tags                   | OpenAPI tags                                | array   | ['pet','user']                            |\n| inverseTags            | OpenAPI tags that will be kept              | array   | ['pet','user']                            |\n| operationIds           | OpenAPI operation ID's                      | array   | ['findPetsByStatus','updatePet']          |\n| inverseOperationIds    | OpenAPI operation ID's that will be kept    | array   | ['findPetsByStatus','updatePet']          |\n| operations             | OpenAPI operations                          | array   | ['GET::/pets','PUT::/pets']               |\n| flags                  | Custom flags                                | array   | ['x-exclude','x-internal']                |\n| inverseFlags           | Custom flags that will kept                 | array   | ['x-exclude','x-internal']                |\n| flagValues             | Custom flags with a specific value          | array   | ['x-version: 1.0','x-version: 3.0']       |\n| inverseFlagValues      | Custom flags with a value that will be kept | array   | ['x-version: 1.0','x-version: 3.0']       |\n| responseContent        | Response Content types                      | array   | ['application/json','application/html']   |\n| inverseResponseContent | Response Content types that will kept       | array   | ['application/ld+json']                   |\n| requestContent         | Request Body Content types                  | array   | ['application/json','application/html']   |\n| inverseRequestContent  | Request Body Content types that will kept   | array   | ['application/ld+json']                   |\n| unusedComponents       | Unused components                           | array   | ['examples','schemas']                    |\n| stripFlags             | Custom flags that will be stripped          | array   | ['x-exclude','x-internal']                |\n| preserveEmptyObjects   | Preserve empty object                       | boolean | true OR ['schema']                        |\n| textReplace            | Search \u0026 replace values to replace          | array   | [{'searchFor':'Pet','replaceWith':'Dog'}] |\n\nSome more details on the available filter types:\n\n### Filter - methods/inverseMethods\n\n=\u003e **methods**: Refers to the [Path Item Object](http://spec.openapis.org/oas/v3.0.3.html#operationObject)\n\nThis will remove all fields and attached fields that match the verbs. In the example below, this would mean that\nall `get`, `put`, `post` items would be removed from the OpenAPI document.\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        get:\n            summary: Finds Pets by status\n        put:\n            summary: Update an existing pet\n```\n\n=\u003e **inverseMethods**: This option does the inverse filtering, by keeping only the verbs defined and remove all other verbs.\n\n### Filter - tags\n\n=\u003e **tags**: Refers to the \"tags\" field from the \"Operation\n  Object\" https://spec.openapis.org/oas/v3.0.3.html#operationObject\n\nThis will remove all fields and attached fields that match the tags. In the example below, this would mean that all\nitems with the tags `pet` or `user` would be removed from the OpenAPI document.\n\nFor example:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        put:\n            tags:\n                - pet\n            summary: Update an existing pet\n```\n\n=\u003e **inverseTags**: This option does the inverse filtering, by keeping only the tags defined and remove all other tags, including the operations without a tags.\n\n### Filter - operationIds\n\n=\u003e **operationIds**: Refers to the \"operationId\" field from the [Operation Object](https://spec.openapis.org/oas/v3.0.3.html#operationObject)\n\nThis will remove specific fields and attached fields that match the operation ID's. In the example below, this would\nmean that the item with operationID `findPetsByStatus` would be removed from the OpenAPI document.\n\nFor example:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        get:\n            operationId: findPetsByStatus\n```\n\n=\u003e **inverseTags**: This option does the inverse filtering, by keeping only the operationIds defined and remove all other operationIds, including the operations without an operationId.\n\n### Filter - operations\n\n=\u003e **operations**: Refers to a combination of a OpenAPI method \u0026 path from the [Path Object](https://spec.openapis.org/oas/v3.0.3.html#paths-object)\n\u0026 [Path item](https://spec.openapis.org/oas/v3.0.3.html#path-item-object)\n\nThis will remove specific path items that match the operation definition `PUT::/pets`. In the example below, this would\nmean that the item with the path '/pets' and method 'PUT' would be removed from the OpenAPI document.\n\nFor example:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        get:\n            summary: Finds Pets by status\n        put:\n            summary: Update an existing pet\n```\n\nAn `operationId` is an optional property. To offer support for OpenAPI documents that don't have operationIds, we have\nadded the `operation` definition which is the unique combination of the OpenAPI method \u0026 path, with a `::` separator\nsymbol.\n\nThis will allow filtering for very specific OpenAPI items, without the need of adding operationIds to the OpenAPI\ndocument.\n\nTo facilitate managing the filtering, we have included wildcard options for the `operations` option, supporting the\nmethods \u0026 path definitions.\n\nREMARK: Be sure to put quotes around the target definition.\n\nStrict matching example: `\"GET::/pets\"`\nThis will target only the \"GET\" method and the specific path \"/pets\"\n\nMethod wildcard matching example: `\"*::/pets\"`\nThis will target all methods ('get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace') and the specific\npath \"/pets\"\n\nPath wildcard matching example: `\"GET::/pets/*\"`\nThis will target only the \"GET\" method and any path matching any folder behind the \"/pets\", like \"/pets/123\" and\n\"/pets/123/buy\".\n\nMethod \u0026 Path wildcard matching example: `\"*::/pets/*\"`\nA combination of wildcards for the method and path parts is even possible.\n\n### Filter - flags/inverseFlags\n\n=\u003e **flags**: Refers to a custom property that can be set on any field in the OpenAPI document.\n\nThis will remove all fields and attached fields that match the flags. In the example below, this would mean that all\nitems with the flag `x-exclude` would be removed from the OpenAPI document.\n\nFor example:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        get:\n            x-exclude: true\n```\n\n=\u003e **inverseFlags**: This option does the inverse filtering, by keeping only the operations, components, tags, x-tagGroups that match the flag(s). This is a very aggressive option to keep only the items that are needed.\n\n### Filter - flagValues/inverseFlagValues\n\n=\u003e **flagValues**: Refers to a flag, custom property which can be set on any field in the OpenAPI document, and the combination with the value for that flag.\n\nThis will remove all fields and attached fields that match the flag with the specific value.\n\nA `flagValues` example:\n\n```yaml\nflagValues:\n    - x-version: 1.0\n    - x-version: 3.0\n```\nIn the example below, this would mean that all items with the flag `x-version` that matches `x-version: 1.0` OR `x-version: 3.0` would be removed from the OpenAPI document.\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        get:\n            x-version: 1.0\n```\n\nThe filter option `flagValues` also will remove flags that contain an array of values in the OpenAPI document.\n\nA `flagValues` example:\n\n```yaml\nflagValues:\n    - x-versions: 1.0\n    - x-versions: 2.0\n```\n\nIn the example below, this would mean that all items with the flag `x-versions`, which is an array, that match `x-version: 1.0` OR `x-version: 3.0` would be removed from the OpenAPI document.\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        get:\n            x-versions:\n                - 1.0\n                - 3.0\n                - 5.0\n```\n\nHave a look at [flagValues](test/yaml-filter-custom-flagsvalue-value) and [flagValues for array values](test/yaml-filter-custom-flagsvalue-array) for a practical example.\n\n=\u003e **inverseFlagValues**: This option does the inverse filtering, by keeping only the operations, components, tags, x-tagGroups that match the flag with the specific value. This is a very aggressive option to keep only the items that are needed.\n\n### Filter - responseContent/inverseResponseContent\n\n=\u003e **ResponseContent**: Refers to the [Response Object's content](https://spec.openapis.org/oas/v3.0.3.html#response-object)\n\nA responses `content` filter example:\n\n```yaml\nresponseContent:\n  - application/json\n```\n\nThis will remove all the content that match the media types from the responses. In the example below, this would mean that all `application/json`\ncontent items would be removed from the OpenAPI document\n\nExample before:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n  /pet:\n    post:\n      tags:\n        - pet\n      summary: Add a new pet to the store\n      description: Add a new pet to the store\n      operationId: addPet\n      x-visibility: true\n      responses:\n        '200':\n          description: Successful operation\n          content:\n            application/xml:\n              schema:\n                $ref: '#/components/schemas/Pet'\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Pet'\n        '405':\n          description: Invalid input\n```\n\nExample after:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n  /pet:\n    post:\n      tags:\n        - pet\n      summary: Add a new pet to the store\n      description: Add a new pet to the store\n      operationId: addPet\n      x-visibility: true\n      responses:\n        '200':\n          description: Successful operation\n          content:\n            application/xml:\n              schema:\n                $ref: '#/components/schemas/Pet'\n        '405':\n          description: Invalid input\n```\n\n=\u003e **inverseResponseContent**: This option does the inverse filtering, by keeping only the content with media types defined and remove all other content.\n\n### Filter - requestContent/inverseRequestContent\n\n=\u003e **requestContent**: Refers to the [Request Body Object's content](https://spec.openapis.org/oas/v3.0.3.html#request-body-object)\n\nA  request body `content` filter example:\n\n```yaml\nrequestContent:\n  - application/json\n```\n\nThis will remove all the content that match the media types from the request body. In the example below, this would mean that all `application/json`\ncontent items would be removed from the OpenAPI document.\n\nExample before:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n  /pet:\n    post:\n      tags:\n        - pet\n      summary: Add a new pet to the store\n      description: Add a new pet to the store\n      operationId: addPet\n      x-visibility: true\n      requestBody: \n          content:\n            application/xml:\n              schema:\n                $ref: '#/components/schemas/Pet'\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Pet'\n\n```\n\nExample after:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n  /pet:\n    post:\n      tags:\n        - pet\n      summary: Add a new pet to the store\n      description: Add a new pet to the store\n      operationId: addPet\n      x-visibility: true\n      requestBody:\n          content:\n            application/xml:\n              schema:\n                $ref: '#/components/schemas/Pet'\n```\n\n=\u003e **inverseRequestContent**: This option does the inverse filtering, by keeping only the content with media types defined and remove all other content types from the request body.\n\n### Filter - unusedComponents\n\n=\u003e **unusedComponents**: Refers to a list of [reusable component types]( https://spec.openapis.org/oas/v3.0.3.html#components-object), from which unused items will be removed.\n\nThis option allows you to strip the OpenAPI document from any unused items of the targeted `components` types.\nAny item in the list of OpenAPI `components` that is not referenced as `$ref`, will get marked and removed from the OpenAPI document.\n\nREMARK: We will recursively strip all unused components, with a maximum depth of 10 times. This means that \"nested\" components, that become unused, will also get removed\n\nSupported component types that can be marked as \"unused\":\n- schemas\n- parameters\n- examples\n- headers\n- requestBodies\n- responses\n\n### Filter - textReplace\n\n=\u003e **textReplace**: \"search \u0026 replace\" option to replace text in the OpenAPI specification\n\nThe `textReplace` provides a \"search \u0026 replace\" method, that will search for a text/word/characters in the OpenAPI description, summary, URL fields and replace it with another text/word/characters.\nThis is very useful to replace data in the OpenAPI specification.\n\nA `textReplace` example:\n\n```yaml\ntextReplace:\n    - searchFor: 'Pets'\n      replaceWith: 'Dogs'\n    - searchFor: 'swagger.io'\n      replaceWith: 'openapis.org'\n```\n\nThis will replace all \"Pets\" with \"Dogs\" \u0026 \"swagger.io\" with \"openapi.org\" in the OpenAPI document.\n\n### Filter - stripFlags\n\n=\u003e **stripFlags**: Refers to a list of custom properties that can be set on any field in the OpenAPI document.\n\nThe `stripFlags` will remove only the flags, the linked parent and properties will remain. In the example below, this would mean that all\nflags `x-exclude` itself would be stripped from the OpenAPI document.\n\nExample before:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        get:\n          x-exclude: true\n          summary: Finds Pets by status\n```\n\nExample after:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        get:\n          summary: Finds Pets by status\n```\n\n### Filter - preserveEmptyObjects\n\n=\u003e **preserveEmptyObjects**: Refers to any properties of your OpenAPI document, from which empty object values would be kept.\n\nThe `preserveEmptyObjects` will preserve all empty objects if set to `true`.\n\nYou can also pass a list of keys from which preserve empty objects. For instance a `['schema']` value would only prevent removal of empty objects having for key `schema`.\n\nREMARK: Please note that openapi-format default behavior is to remove all empty objects from your document, except for items of examples, security, schemas, default, oneOf, allOf.\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        post:\n          requestBody:\n            description: Create a new pet in the store\n            required: true\n            content:\n              application/json:\n                schema: {}\n```\n\nExample after (with `preserveEmptyObjects: false`):\n\n```yaml\nopenapi: 3.0.0\ninfo:\n    title: API\n    version: 1.0.0\npaths:\n    /pets:\n        post:\n          requestBody:\n            description: Create a new pet in the store\n            required: true\n            content:\n              application/json: {}\n```\n\n## OpenAPI formatting configuration options\n\nTools like [spectral](https://github.com/stoplightio/spectral) or [speccy](https://speccy.io/), or any of the [linting tools](https://nordicapis.com/8-openapi-linters/), provide a manner to validate \u0026 lint OpenAPI specifications to be uniform. The linting tool informs about the incorrect usage of OpenAPI properties \u0026 inconsistent field names.\nThis is very useful and helps to guard the quality of the OpenAPI specification. They inform which fields to correct so that the specification will comply with all the defined linting rules.\n\nThe openapi-format CLI formatting option can assist with keeping the field names consistent by automatically changing the casing of the properties/keys/names for the different elements in the OpenAPI document.\nThe desired casing can be defined per OpenAPI key/element (see list below).\nThe keys that are not specified will keep their casing like it is in the original OpenAPI document, so only for defined fields, the casing will be changed.\n\n| Key                        | Description                                                                                          | OpenAPI reference                                                         |\n|----------------------------|------------------------------------------------------------------------------------------------------| ------------------------------------------------------------------------- |\n| operationId                | Changes operation ID's that are part of the Operations Object                                        | [operation-object](https://spec.openapis.org/oas/v3.0.3.html#operation-object)|\n| properties                 | Changes property keys of the schemas of the inline response/requestBody \u0026 components                 | [schemaObject](https://spec.openapis.org/oas/v3.0.3.html#schemaObject) |\n| parametersCookie           | Changes the cookie name of the parameters inline \u0026 models in the components                          | [parameter-object](https://spec.openapis.org/oas/v3.0.3.html#parameter-object) |\n| parametersPath             | Changes the path name of the parameters inline \u0026 models in the components                            | [parameter-object](https://spec.openapis.org/oas/v3.0.3.html#parameter-object) |\n| parametersHeader           | Changes the header name of the parameters inline \u0026 models in the components                          | [parameter-object](https://spec.openapis.org/oas/v3.0.3.html#parameter-object) |\n| parametersQuery            | Changes the query name of the parameters inline \u0026 models in the components                           | [parameter-object](https://spec.openapis.org/oas/v3.0.3.html#parameter-object) |\n| componentsParametersCookie | Changes the key of the cookie models in the components parameters sections \u0026 \"$ref\" links            | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsParametersPath   | Changes the key of the path models in the components parameters sections \u0026 \"$ref\" links              | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsParametersQuery  | Changes the key of the query models in the components parameters sections \u0026 \"$ref\" links             | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsParametersHeader | Changes the key of the header models in the components parameters sections \u0026 \"$ref\" links            | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsSchemas          | Changes the key of the schema models in the components sections \u0026 \"$ref\" links                       | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsExamples         | Changes the key of the example models in the components sections \u0026 \"$ref\" links                      | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsHeaders          | Changes the key of the header models in the components sections \u0026 \"$ref\" links                       | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsResponses        | Changes the key of the response models in the components sections \u0026 \"$ref\" links                     | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsRequestBodies    | Changes the key of the request body models in the components sections \u0026 \"$ref\" links                 | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n| componentsSecuritySchemes  | Changes the key of the security schemes in the components sections \u0026 \"$ref\" links                    | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |\n\n### Casing options\n\n| Casing type      | Casing alias | Description                                       | Example          |\n| -----------------| ------------ | ------------------------------------------------- | --------------- |\n| 🐪 camelCase     | camelCase    | converts a strings to `camelCase`                 | `openapiFormat`  |\n| 👨‍🏫 PascalCase    | PascalCase   | converts a strings to `PascalCase`                | `OpenapiFormat`  |\n| 🥙 kebab-case    | kebabCase    | converts a strings to `kebab-case`                | `openapi-format` |\n| 🚂 Train-Case    | TrainCase    | converts a strings to `Train-Case`                | `Openapi-Format` |\n| 🐍 snake_case    | snakeCase    | converts a strings to `snake_case`                | `openapi_format` |\n| 🕊 Ada_Case      | AdaCase      | converts a strings to `Ada_Case`                  | `Openapi_Format` |\n| 📣 CONSTANT_CASE | constantCase | converts a strings to `CONSTANT_CASE`             | `OPENAPI_FORMAT` |\n| 👔 COBOL-CASE    | cobolCase    | converts a strings to `COBOL-CASE`                | `OPENAPI-FORMAT` |\n| 📍 Dot.notation  | dotNotation  | converts a strings to `Dot.notation`              | `openapi.format` |\n| 🛰 Space case    | spaceCase    | converts a strings to `Space case` (with spaces)  | `openapi format` |\n| 🏛 Capital Case  | capitalCase  | converts a strings to `Capital Case` (with spaces)| `Openapi Format` |\n| 🔡 lower case    | lowerCase    | converts a strings to `lower case` (with spaces)  | `openapi format` |\n| 🔠 UPPER CASE    | upperCase    | converts a strings to `UPPER CASE` (with spaces)  | `OPENAPI FORMAT` |\n\n\u003e REMARK: All special characters are stripped during conversion, except for the `@` and `$`, since they can be part of the query strings.\n\nThe casing options are provided by the nano NPM [case-anything](https://github.com/mesqueeb/case-anything) package.\n\n### Format casing - operationId\n\n=\u003e **operationId**: Refers to the `operationId` properties in the OpenAPI document.\n\nFormatting casing example:\n\n```yaml\noperationId: kebab-case\n```\n\nExample before:\n\n```yaml\nopenapi: 3.0.3\npaths:\n    /pets:\n        get:\n          operationId: getPets\n```\n\nopenapi-format will format the \"getPets\" from the original camelcase to kebab-case.\n\nExample after:\n\n```yaml\nopenapi: 3.0.3\npaths:\n    /pets:\n        get:\n          operationId: get-pets\n```\n\n### Format casing - model \u0026 schema properties\n\n=\u003e **properties**: Refers to all the schema properties, that are defined inline in the paths request bodies \u0026 responses and the models in the components section of the OpenAPI document.\n\nFormatting casing example:\n\n```yaml\nproperties: snake_case\n```\n\nExample before:\n\n```yaml\nopenapi: 3.0.3\ncomponents:\n    schemas:\n        UserModel:\n            type: object\n            properties:\n                id:\n                    type: integer\n                    example: 10\n                emailAddress:\n                    type: string\n                    example: john@doe.com\n                firstName:\n                    type: string\n                    example: John\n```\n\nThe CLI will format all the properties like: \"id\", \"username\", \"firstName\" from the original camelcase to snake_case.\n\nExample after:\n\n```yaml\nopenapi: 3.0.3\ncomponents:\n    schemas:\n        UserModel:\n            type: object\n            properties:\n                id:\n                    type: integer\n                    example: 10\n                email_address:\n                    type: string\n                    example: john@doe.com\n                first_name:\n                    type: string\n                    example: John\n```\n\n### Format casing - component keys\n\n=\u003e **componentsSchemas / componentsExamples / componentsParametersCookie / componentsParametersHeader / componentsParametersQuery / componentsParametersQuery / componentsParametersPath / componentsHeaders / componentsResponses / componentsRequestBodies / componentsSecuritySchemes**: Refers to all the model objects that are defined in the components section of the OpenAPI document.\n\nFormatting casing example:\n\n```yaml\ncomponentsSchemas: PascalCase\n```\n\nExample before:\n\n```yaml\nopenapi: 3.0.3\npaths:\n    /orders:\n        get:\n            responses:\n                content:\n                    application/json:\n                        schema:\n                            $ref: '#/components/schemas/order-model'\ncomponents:\n    schemas:\n        userModel:\n            type: object\n        order-model:\n            type: object\n        pet_model:\n            type: object\n```\n\nopenapi-format will format all the component keys like: \"userModel\", \"order-model\", \"pet_model\" to PascalCase, including formatting all the \"$ref\" used in the OpenAPI document.\n\nExample after:\n\n```yaml\nopenapi: 3.0.3\npaths:\n    /orders:\n        get:\n            responses:\n                content:\n                    application/json:\n                        schema:\n                            $ref: '#/components/schemas/OrderModel'\ncomponents:\n    schemas:\n        UserModel:\n            type: object\n        OrderModel:\n            type: object\n        PetModel:\n            type: object\n```\n\n### Format casing - parameter names\n\n=\u003e **componentsParametersCookie / componentsParametersPath / componentsParametersQuery / componentsParametersHeader**: Refers to \"name\" in the Parameters types: Path, Query or Header, which can be defined inline in the Path or as a reference in the components of the OpenAPI document.\n\nFormatting casing example:\n\n```yaml\ncomponentsParametersPath: kebab-case\n```\n\nExample before:\n\n```yaml\nopenapi: 3.0.3\npaths:\n    '/pet/{petId}':\n        get:\n            parameters:\n                - name: petId\n                  in: path\n                  description: ID of pet to return\n                - $ref: '#/components/parameters/LimitParam'\ncomponents:\n    parameters:\n        LimitParam:\n            name: limitParam\n            in: query\n            description: max records to return\n```\n\nThe CLI will format the \"name\" of the parameters: Path, Query or Header like: \"petId\", \"limitParam\" to kebab-case in the OpenAPI document.\n\nExample after:\n\n```yaml\nopenapi: 3.0.3\npaths:\n    '/pet/{petId}':\n        get:\n            parameters:\n                - name: pet-id\n                  in: path\n                  description: ID of pet to return\n               - $ref: '#/components/parameters/LimitParam'\ncomponents:\n    parameters:\n        LimitParam:\n            name: limit-param\n            in: query\n            description: max records to return\n```\n\n### OpenAPI Generate Options\n\nThe OpenAPI formatting tool allows you to generate various elements such as `operationId`, and more using customizable templates. These templates enable dynamic generation of missing or incomplete values in your OpenAPI specification, ensuring consistency and adherence to your conventions.\n\nOptions for generating elements:\n\n- `operationIdTemplate`: Generate the `operationId` using placeholders like `\u003cmethod\u003e`, `\u003cpathPart2\u003e`, etc.\n- `overwriteExisting`: Set to `true` or `false` to control whether existing values should be overwritten (default: `false`).\n\n| Key                 | Options                        | OpenAPI Reference                                                              |\n|---------------------|--------------------------------|--------------------------------------------------------------------------------|\n| operationIdTemplate | Customizable with placeholders | [operation-object](https://spec.openapis.org/oas/v3.0.3.html#operation-object) |\n| overwriteExisting   | `true` / `false`               | N/A                                                                            |\n\nSee [CLI generate usage](#cli-generate-usage) for an example and the available template options.\n\n## CLI sort usage\n\n- Format a spec with the default sorting and saves it as a new JSON file\n\n```shell\n$ openapi-format openapi.json -o openapi-formatted.json\n```\n\n- Format a remote spec with the default sorting and saves it as a new JSON file\n\n```shell\n$ openapi-format https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/api-with-examples.json -o openapi-formatted.json\n```\n\n- Format an OpenAPI JSON document with the default sorting and saves it as a new YAML file\n\n```shell\n$ openapi-format openapi.json -o openapi.yaml\n```\n\n- Format an OpenAPI document using a configuration file containing all the options that would otherwise be passed via the CLI. \n\n```shell\n$ openapi-format openapi.yaml --configFile openapi-format-options.json\n```\n\nThe formatting will happen based on all the options set in the `openapi-format-options.json` file. All the\navailable [OpenAPI format options](https://github.com/thim81/openapi-format#openapi-format-options) can be used in the config file.\n\n- Format an OpenAPI document with the default sorting and output it as JSON to STDOUT\n\n```shell\n$ openapi-format openapi.json --json\n```\n\n- Format an OpenAPI document with the default sorting and output it as YAML to STDOUT\n\n```shell\n$ openapi-format openapi.json --yaml\n```\n\n- Format an OpenAPI JSON document with the default sorting and save it as YAML\n\n```shell\n$ openapi-format openapi.json -o openapi.yaml\n```\n\n- Format an OpenAPI document but skip the sorting and save it as a new JSON file\n\n```shell\n$ openapi-format openapi.json -o openapi-formatted.json --no-sort\n```\n\nThis should keep the OpenAPI fields in the same order. This can be needed, when you only want to do a filtering or\nrename action.\n\n- Convert the OpenAPI 3.0 document to OpenAPI 3.1 but skip the sorting and save it as a new YAML file\n\n```shell\n$ openapi-format openapi.yaml -o openapi-3.1.yaml --no-sort --convertTo \"3.1\"\n```\n\nThis will convert the OpenAPI 3.0 document into version 3.1 of OpenAPI, without any ordering or filtering.\nDuring the conversion, openapi-format will transform all OpenAPI 3.0 properties into the OpenAPI 3.1 properties, as described in the [migration guide from\nPhil Sturgeon](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0).\n\n- Format an OpenAPI document, including sorting all elements in the components section\n\n```shell\n$ openapi-format openapi.json -o openapi-formatted.json --sortComponentsFile ./test/json-sort-components/customSortComponents.json\n```\n\nThis will sort all elements in the components ( components/schemas, components/parameters, components/headers,\ncomponents/requestBodies, components/responses, ...) section by alphabet.\n\n## CLI filter usage\n\n- Format an OpenAPI document by filtering fields, default sorting and saves it as a new file\n\nWhen you want to strip certain methods ,tags, operationIds, operations, flags you can pass a `filterFile` which contains the\nspecific values for the methods ,tags, operationIds, operations, flags.\n\nThis can be useful to combine with the sorting, to end up with an order and filtered OpenAPI document.\n\nexample:\n\n```shell\n$ openapi-format openapi.json -o openapi-formatted.json --filterFile customFilter.yaml\n```\n\nwhere the `customFilter.yaml` would contain a combination of all the elements you want to filter out.\n\n```yaml\nflags:\n    - x-visibility\nflagValues: [ ]\ntags: [ ]\noperationIds:\n    - addPet\n    - findPetsByStatus\n```\n\n## CLI OpenAPI Overlay Usage\n\nThe OpenAPI Overlay functionality allows users to apply actions such as updates and removals to an OpenAPI Specification (OAS). This feature is useful for dynamically modifying OAS documents during development, testing, or publishing workflows.\n\n### What is an OpenAPI Overlay?\nAn [OpenAPI Overlay](https://spec.openapis.org/overlay/v1.0.0.html) is a specification that defines a structured set of actions to be applied to an existing OpenAPI document. It enables:\n\n- Updating existing fields, such as descriptions, parameters, or endpoints.\n- Adding new fields or objects to the OpenAPI document.\n- Removing fields or objects that are no longer relevant.\n\nAn overlay document follows the structure below:\n\n```\noverlay: 1.0.0\ninfo:\n  title: Example Overlay\n  version: 1.0.0\nactions:\n  - target: \"$\"   // JSONPath definition of the targetted element of the document\n    update: // The action to be applied: update or remove\n      info:\n        description: \"Updated description for the OpenAPI specification.\"\n  - target: \"$.paths['/example']\"\n    update:\n      get:\n        description: \"Updated GET description for /example endpoint.\"\n  - target: \"$.paths['/example'].get.parameters\"\n    remove: true   # Example of removing an element\n```\n\nFore more information about the OpenAPI Overlay options, see [OpenAPI Overlay Specification 1.0.0](https://www.openapis.org/blog/2024/10/22/announcing-overlay-specification) \n\nUse the `--overlayFile` option to specify the overlay file and apply it to your OpenAPI document.\n\nexample:\n```shell\n$ openapi-format openapi.yaml --overlayFile overlay.yaml -o openapi-updated.yaml\n```\n\n## CLI generate usage\n\n- Generate OpenAPI elements and saves it as a new file\n\nThe OpenAPI formatting tool allows you to generate OpenAPI elements, such as `operationId`, `summary`, and more, based on configurable templates. The generated elements will be saved to the output OpenAPI file.\n\nYou can also combine generation with filtering and sorting to customize the output.\n\nexample:\n\n```shell\n$ openapi-format openapi.json -o openapi-formatted.json --generateFile customGenerate.yaml\n```\n\nwhere the `customGenerate.yaml` would contain a combination of all the elements you to generate.\n\n```yaml\noperationIdTemplate: \"\u003cmethod\u003e_\u003cpathPart2\u003e\"\noverwriteExisting: false\n```\n\n**Template Options:**\nIn the customGenerate.yaml, you can define templates for various OpenAPI properties using dynamic placeholders. These placeholders will be replaced by actual values from the OpenAPI operations. Below is a list of available placeholders and what they represent:\n\n- `\u003coperationId\u003e` : The operationId of the OpenAPI operation. Example: leadsAll\n- `\u003cmethod\u003e` : The HTTP method of the OpenAPI operation. Example: GET\n- `\u003cpath\u003e` : The path of the OpenAPI operation. Example: /crm/leads\n- `\u003cpathRef\u003e` : The path reference of the OpenAPI operation. Example: GET::/crm/leads\n- `\u003ctag\u003e` : The first tag name of the OpenAPI operation. Example: Leads\n- `\u003ctag1\u003e` : The first tag name of the OpenAPI operation. Example: Leads\n- `\u003ctag2\u003e` : The second tag name of the OpenAPI operation, if more than one tag is defined. Example: CRM\n- `\u003ctagn\u003e` : The nth tag name of the OpenAPI operation if more than one tag is defined.\n- `\u003cpathPart1\u003e` : The first part of the path of the OpenAPI operation. Example: crm\n- `\u003cpathPart2\u003e` : The second part of the path of the OpenAPI operation. Example: leads\n- `\u003cpathPartn\u003e` : The nth part of the path of the OpenAPI operation.\n\nYou can also include static text in the templates, which will be merged with the dynamic placeholders. For example:\n\n```yaml\noperationIdTemplate: \"Prefix_\u003cmethod\u003e_\u003cpathPart2\u003e_Handler\"\n```\n\n**Configuration Options:**\n\n- `operationIdTemplate`: Template for generating `operationId`. Use dynamic placeholders like \u003cmethod\u003e and \u003cpathPart2\u003e.\n- `overwriteExisting`: Set to `true` or `false` to control whether existing values should be overwritten. Default: `false`.\n\n## CLI casing usage\n\n- Generate OpenAPI elements and saves it as a new file\n\nThe OpenAPI formatting tool allows you to enforce consistent casing styles across various OpenAPI elements, such as `operationId`, `summary`, `parameters`, and more. The specified casing preferences will be applied to the relevant elements and saved to the output OpenAPI file.\n\nexample:\n\n```shell\n$ openapi-format openapi.json -o openapi-formatted.json --casingFile customCasing.yaml\n```\n\nwhere the `customCasing.yaml` would contain a casing preferences for the specified of the elements.\n\nIn this example, the customCasing.yaml file would contain the desired casing preferences for specific OpenAPI elements.\n\n```yaml\noperationId: snake_case\nproperties: camelCase\n\nparametersQuery: kebab-case\nparametersHeader: kebab-case\nparametersPath: snake_case\n\ncomponentsExamples: PascalCase\ncomponentsSchemas: camelCase\ncomponentsHeaders: kebab-case\ncomponentsResponses: snake_case\ncomponentsRequestBodies: snake_case\ncomponentsSecuritySchemes: PascalCase\n\ncomponentsParametersQuery: snake_case\ncomponentsParametersHeader: kebab-case\ncomponentsParametersPath: camelCase\n```\n\n**Casing Options:**\nIn the customCasing.yaml, you can define the casing style for various OpenAPI properties, allowing you to customize the appearance of your document consistently.\n\n- `operationId`: Defines the casing for operation IDs. Example: snake_case, PascalCase, or camelCase.\n- `properties`: Sets the casing for properties within components. Example: camelCase.\n- `parametersQuery`, `parametersHeader`, `parametersPath`: Define different casing styles for parameters based on their location (query, header, path). Example: snake_case, kebab-case.\n- and many more\n\nSee [OpenAPI formatting configuration options](#openapi-formatting-configuration-options) for the full list of casing options\n\n## CLI Bundle \u0026 Split usage\n\n- **Bundling**: Create a self-contained OpenAPI file that can be used for documentation generation or API validation tools that don't support external references.\n\n- **Splitting**: Generate a modular OpenAPI structure during development or testing, making it easier to manage changes to individual paths or components without altering the entire document.\n\n### Splitting the OpenAPI Document\n\nThe `--split` option splits the OpenAPI document into a modular multi-file structure. This structure makes it easier to manage larger specifications by separating paths, components (schemas, paramaters, ...) into individual files.\n\nExample: Splitting the Document\n\n```shell\n$ openapi-format openapi.json -o ./openapi-split/openapi.yaml --split\n```\n\nThis command will take the openapi.json and split it into multiple files, stored under the ./openapi-split/ directory. \n\nThe resulting structure might look like this:\n\n```bash\n./openapi-split/\n├── openapi.yaml\n├── paths/\n│   ├── /pets.yaml\n│   └── /pets/{petId}.yaml\n├── components/\n├── schemas/\n│   ├── Pet.yaml\n│   └── Error.yaml\n├── parameters/\n│   └── petId.yaml\n```\n\nThe main openapi.yaml file will contain references to these newly created files using $ref, making the structure modular and easier to navigate.\n\n###  Bundling the OpenAPI Document\n\nThe `--no-bundle` option allows you to control whether local and remote $ref references are bundled into the final document. \n\nBy default, all $ref references are dereferenced, resulting in a single, self-contained OpenAPI file. However, in some cases, you might prefer to keep the $ref references intact, especially if you're working with external references or want to maintain a modular structure.\n\nExample: Default Bundling\n```shell\n$ openapi-format input.json -o bundled-openapi.json\n```\n\nThis example produces a fully dereferenced dereferenced-openapi.json, where all local and remote $ref references are resolved into the file.\nThis is the default behaviour.\n\nExample: No Bundling\n\n```shell\n$ openapi-format openapi.json -o openapi.json --no-bundle\n```\n\nIn this case, the resulting bundled-openapi.json will preserve all $ref references as they are in the original document.\n\n## CLI rename usage\n\n- Format an OpenAPI document by changing the title and saves it as a new JSON file\n\nDuring CI/CD pipelines, you might want to create different results of the OpenAPI document. Having the option to rename\nthem might make it easier to work with the results, so that is why we provide this command option.\n\n```shell\n$ openapi-format openapi.json -o openapi.json --rename \"OpenAPI Petstore - OpenAPI 3.0\"\n```\n\nwhich results in\n\n**before**\n\n```json\n{\n    \"openapi\": \"3.0.2\",\n    \"info\": {\n        \"title\": \"Petstore - OpenAPI 3.0\",\n```\n\n**after**\n\n```json\n{\n    \"openapi\": \"3.0.2\",\n    \"info\": {\n        \"title\": \"OpenAPI Petstore - OpenAPI 3.0\",\n```\n\n## CLI convertTo usage\n\n\u003e 🏗 BETA NOTICE: This feature is considered BETA since we are investigating the configuration syntax and extra formatting/casing capabilities.\n\n- Format \u0026 convert the OpenAPI document to OpenAPI version 3.1\n\nopenapi-format can help you to upgrade your current OpenAPI 3.0.x document to the latest version OpenAPI 3.1.\n\n```shell\n$ openapi-format openapi.json -o openapi-3.1.json --convertTo \"3.1\"\n```\n\nwhich results in all the changes described in the [migration guide from Phil Sturgeon](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)\n\n**before**\n\n```json\n{\n    \"openapi\": \"3.0.2\",\n    \"info\": {\n        \"title\": \"Petstore - OpenAPI\",\n```\n\n**after**\n\n```json\n{\n    \"openapi\": \"3.1.0\",\n    \"info\": {\n        \"title\": \"OpenAPI Petstore - OpenAPI\",\n```\n\n## CLI configuration usage\n\nThe openapi-format CLI supports bundling all options in a single configuration file. This can simplify management, especially for CI/CD pipelines where configurations are stored in version control systems.\n\n### Using the --configFile option\n\nYou can pass a configuration file containing all the options that would otherwise be passed via the CLI. This helps in centralizing the configuration for your OpenAPI formatting operations.\n\nExample:\n\n```shell\n$ openapi-format openapi.json --configFile openapi-format-options.json\n```\nThe formatting will happen based on all the options set in the `openapi-format-options.json` file. All the\navailable [OpenAPI format options](https://github.com/thim81/openapi-format#openapi-format-options) can be used in the config file.\n\nThe openapi-format-options.json file might look like this:\n\n```json\n{\n  \"sort\": true,\n  \"casingSet\": {\n    \"operationId\": \"camelCase\",\n    \"properties\": \"snake_case\"\n  },\n  \"filterSet\": {\n    \"tags\": [\"internal\", \"beta\"]\n  },\n  \"generateSet\": {\n    \"operationIdTemplate\": \"\u003cmethod\u003e_\u003cpathPart2\u003e_Handler\"\n  }\n}\n```\n\nAlternatively, you can reference external files for each setting using the corresponding File properties.\n\n```json\n{\n    \"sortFile\": \"customSort.json\",\n    \"casingFile\": \"casing-rules.json\",\n    \"filterFile\": \"filter-rules.json\",\n    \"generateFile\": \"generate-rules.json\"\n}\n```\n\nIn this case, the settings will be loaded from the external files, and they override any inline configurations.\n\n**Define sort, filter, casing, generate options**\n\nYou can either pass the settings inline or reference an external file using the appropriate File property:\n\n- **sortSet** / **sortFile**: Sort the fields in the OpenAPI document based on the order defined in the sort settings.\n\n  - Inline: Pass the sort order directly using sortSet in the config file.\n  - File: Use sortFile to specify the path to a local or remote JSON/YAML file containing custom sorting rules.\n\n- **casingSet** / **casingFile**: Define the casing convention for operationId, parameters, properties, etc.\n\n  - Inline:\n    ```json\n    \"casingSet\": {\n      \"operationId\": \"camelCase\",\n      \"properties\": \"PascalCase\"\n    }\n    ```\n\n  - File: Use casingFile to specify the path to a local or remote JSON/YAML file containing casing rules.\n\n- **filterSet** / **filterFile**: Filter out specific tags, paths, or components from the OpenAPI document.\n\n  - Inline:\n    ```json\n    \"filterSet\": {\n      \"tags\": [\"internal\", \"beta\"]\n    }\n    ```\n\n  - File: Use filterFile to specify the path to a local or remote JSON/YAML file containing filter rules.\n\n- **generateSet** / **generateFile**: Automatically generate operationId, summary, and other elements based on predefined templates.\n\n  - Inline:\n    ```json\n    \"generateSet\": {\n      \"operationIdTemplate\": \"\u003cmethod\u003e_\u003cpathPart2\u003e_Handler\"\n    }\n    ```\n\n  - File: Use generateFile to specify the path to a local or remote JSON/YAML file containing generate rules.\n\n\n### Using .openapiformatrc\n\nIn addition to specifying a configuration file using `--configFile`, openapi-format also supports automatically loading a configuration file named `.openapiformatrc` from the current directory. If this file is present, it will be used as the configuration source, and individual options passed via the CLI will override the settings from this file.\n\nExample of a .openapiformatrc file:\n\n```json\n{\n  \"output\": \"openapi-final.yaml\",  \n  \"sort\": true,\n  \"filterSet\": {\n      \"tags\": [\"internal\", \"beta\"]\n  }\n}\n```\n\n## AsyncAPI documents\n\nFor handling AsyncAPI documents, we have created a separate\npackage [asyncapi-format](https://github.com/thim81/asyncapi-format) to allow customisation specific for AsyncAPI\nuse-cases.\n\n## Stoplight Studio\n\nWe have adopted the YAML parsing style from [Stoplight Studio](https://stoplight.io/studio/), by leveraging\nthe [@stoplight/yaml](https://www.npmjs.com/package/@stoplight/yaml) package for handling the parsing of OpenAPI YAML\nfiles.\n\nBy using the Stoplight YAML parsing, the results will be slightly different from when using a normal YAML parsing\nlibrary, like [js-to-yaml](https://www.npmjs.com/package/js-yaml). We appreciate the Stoplight Studio tool, since it is\nan excellent GUI for working with OpenAPI documents for non-OpenAPI experts who will be contributing changes. By\nadopting the Stoplight Studio YAML parsing, the potential risk of merge conflicts will be lowered, which is the main\nreason why we opted for using the @stoplight/yaml package.\n\n## Credits\n\nThis package is inspired by\nthe [@microsoft.azure/format-spec](https://www.npmjs.com/package/@microsoft.azure/format-spec) from [@fearthecowboy](https://github.com/fearthecowboy). The\noriginal code was not available on GitHub, with the last update being 3 years ago, so to improve support and extend it we\ntried to reproduce the original functionality.\n\nThe filter capabilities from `openapi-format` are inspired by the work from [@MikeRalphson](https://github.com/mikeralphson) on\nthe [openapi-filter](https://github.com/Mermade/openapi-filter) package.\n\nThe casing options available in `openapi-format` are powered by the excellent [case-anything](https://github.com/mesqueeb/case-anything) nano package from Luca Ban ([@mesqueeb](https://github.com/mesqueeb)).\n\n\u003ca href=\"https://www.jetbrains.com/\" target=\"_blank\"\u003e\n\u003cimg src=\"https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png\" alt=\"JetBrains logo.\" width=\"200px\"\u003e\n\u003c/a\u003e\n\nSpecial thanks to [JetBrains](https://www.jetbrains.com/) for their continuous sponsorship of this project over the last 3 years, and for their support to open-source software (OSS) initiatives.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthim81%2Fopenapi-format","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthim81%2Fopenapi-format","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthim81%2Fopenapi-format/lists"}