{"id":15699078,"url":"https://github.com/thim81/asyncapi-format","last_synced_at":"2025-05-08T22:24:06.190Z","repository":{"id":37491002,"uuid":"354052956","full_name":"thim81/asyncapi-format","owner":"thim81","description":"Format an AsyncAPI document by ordering, formatting and filtering fields.","archived":false,"fork":false,"pushed_at":"2022-01-28T09:59:56.000Z","size":701,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-16T13:06:22.412Z","etag":null,"topics":["asyncapi","asyncapi-tooling","asyncapi-tools","cli","filtering","formatting","sorting"],"latest_commit_sha":null,"homepage":"","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}},"created_at":"2021-04-02T15:05:35.000Z","updated_at":"2022-11-23T22:00:20.000Z","dependencies_parsed_at":"2022-09-06T04:12:07.052Z","dependency_job_id":null,"html_url":"https://github.com/thim81/asyncapi-format","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thim81%2Fasyncapi-format","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thim81%2Fasyncapi-format/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thim81%2Fasyncapi-format/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thim81%2Fasyncapi-format/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thim81","download_url":"https://codeload.github.com/thim81/asyncapi-format/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253156195,"owners_count":21862850,"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":["asyncapi","asyncapi-tooling","asyncapi-tools","cli","filtering","formatting","sorting"],"created_at":"2024-10-03T19:38:09.236Z","updated_at":"2025-05-08T22:24:06.172Z","avatar_url":"https://github.com/thim81.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![asyncapi-format icon](./assets/asyncapi-format-logo.svg)\n\n\u003ca href=\"https://www.npmjs.com/package/asyncapi-format\" alt=\"Latest Stable Version\"\u003e![npm](https://img.shields.io/npm/v/asyncapi-format.svg)\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/asyncapi-format\" alt=\"Total Downloads\"\u003e![npm](https://img.shields.io/npm/dw/asyncapi-format.svg)\u003c/a\u003e\n\n# asyncapi-format\n\nFormat an AsyncAPI document by ordering, formatting and filtering fields.\n\nThe asyncapi-format CLI can load an AsyncAPI file, sorts the AsyncAPI fields by ordering them in a hierarchical order, format the casing of the fields and\ncan output the file with clean indenting, to either JSON or YAML.\n\nNext to the ordering \u0026 formatting, the CLI provides additional options to filter fields \u0026 parts of the AsyncAPI document based on\nflags, tags, operations and operationID's.\n\n## Table of content\n* [Use-cases](#use-cases)\n* [Features](#features)\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* [AsyncAPI format CLI options](#asyncapi-format-cli-options)\n* [AsyncAPI sort configuration options](#asyncapi-sort-configuration-options)\n* [AsyncAPI formatting configuration options](#asyncapi-formatting-configuration-options)\n* [AsyncAPI filter options](#asyncapi-filter-options)\n* [CLI sort usage](#cli-sort-usage)\n* [CLI filter usage](#cli-filter-usage)\n* [CLI rename usage](#cli-rename-usage)\n* [CLI configuration usage](#cli-configuration-usage)\n* [Credits](#credits)\n\n## Use-cases\n\nWhen working on large AsyncAPI 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\nThe filtering is a handy add-on to remove specific elements from the AsyncAPI like internal endpoints, beta tags, ...\nThis can be useful in CI/CD pipelines, where the AsyncAPI is used as the source for other documents like Web documentation\nor for generating event producers/consumers.\n\n## Features\n\n- [x] Order AsyncAPI fields in a default order\n- [x] Order AsyncAPI 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 AsyncAPI files based on operations\n- [x] Filter AsyncAPI files based on flags\n- [x] Filter AsyncAPI files based on flags values\n- [x] Filter AsyncAPI files based on tags\n- [x] Filter AsyncAPI files based on operationID's\n- [x] Strip flags from AsyncAPI files\n- [x] Strip unused components from AsyncAPI files\n- [x] Rename the AsyncAPI title\n- [x] Support AsyncAPI documents in JSON format\n- [x] Support AsyncAPI documents in YAML format\n- [x] Format via CLI\n- [x] Format via config files\n- [x] Use as a Module\n- [x] Support for AsyncAPI 2.x\n\n## Installation\n\n### Local Installation (recommended)\n\nWhile possible to install globally, we recommend that you add the asyncapi-format CLI to the `node_modules` by using:\n\n```shell\n$ npm install --save asyncapi-format\n```\n\nor using yarn...\n\n```shell\n$ yarn add asyncapi-format\n```\n\nNote that this will require you to run the asyncapi-format CLI with `npx asyncapi-format your-asyncapi-file.yaml` or, if\nyou are using an older versions of npm, `./node_modules/.bin/asyncapi-format your-asyncapi-file.yaml`.\n\n### Global Installation\n\n```shell\n$ npm install -g asyncapi-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 asyncapi-format your-asyncapi-file.yaml\n```\n\n## Command Line Interface\n\n```\nasyncapi-format.js \u003cinput-file\u003e -o [ouptut-file] [options]\n\nArguments:\n  input-file   the AsyncAPI document, can be either a .json or .yaml file\n  ouptut-file  the output file is optional and be either a .json or .yaml file.\n\nOptions:\n\n  --output, -o          Save the formatted AsyncAPI file as JSON/YAML           [path]\n  \n  --sortFile            The file to specify custom AsyncAPI fields ordering     [path]\n  --casingFile          The file to specify casing rules                        [path]\n  --filterFile          The file to specify filter rules                        [path]\n    \n  --no-sort             Don't sort the AsyncAPI file                         [boolean]\n  --sortComponentsFile  The file with components to sort alphabetically         [path]\n  \n  --rename              Rename the AsyncAPI title                             [string]\n\n  --configFile          The file with the AsyncAPI-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  --help                Show help                                            [boolean]\n  --verbose             Output more details of the filter process              [count]\n```\n\n## AsyncAPI format CLI options\n\n| Parameter            | Alias         | Description                                                                 | Input type   | Default                    | Info      |\n|----------------------|---------------|-----------------------------------------------------------------------------|--------------|----------------------------|-----------|\n| file                 |               | the original AsyncAPI file                                                  | path to file |                            | required  |\n| --output             | -o            | save the formatted AsyncAPI file as JSON/YAML                               | path to file |                            | optional  |\n| --sortFile           | -s            | the file to specify custom AsyncAPI 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         | -c            | the file to specify casing setting                                          | path to file |                            | optional  |\n| --no-sort            |               | don't sort the AsyncAPI file                                                | boolean      | FALSE                      | optional  |\n| --sortComponentsFile |               | sort the items of the components (schemas, parameters, ...) by alphabet     | path to file | defaultSortComponents.json | optional  |\n| --rename             |               | rename the AsyncAPI title                                                   | 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| --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## AsyncAPI sort configuration options\n\nThe CLI will sort the AsyncAPI document in the defined order liked defined per AsyncAPI key/element. The fields that are\nnot specified will keep their order like it is in the original AsyncAPI document, so only defined fields will be\nre-ordered.\n\nThe default sorting based on the defined order (listed in the table below), which is stored in\nthe [defaultSort.json](https://github.com/thim81/asyncapi-format/blob/main/defaultSort.json) file.\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                                                                                                      | AsyncAPI reference         |\n| ----------- | ----------------------------------------------------------------------------------------------------------------| -------------------------- |\n| root        | - asyncapi\u003cbr\u003e\\- info\u003cbr\u003e\\- servers\u003cbr\u003e\\- channels\u003cbr\u003e\\- components\u003cbr\u003e\\- tags\u003cbr\u003e\\- externalDocs               | [AsyncAPI-object](https://www.asyncapi.com/docs/specifications/2.0.0#A2SObject) |\n| channels    | - description\u003cbr\u003e\\- parameters\u003cbr\u003e\\- subscribe\u003cbr\u003e\\- publish\u003cbr\u003e\\- bindings                                     | [channels-item-object](https://www.asyncapi.com/docs/specifications/2.0.0#channelItemObject) |\n| parameters  | - name\u003cbr\u003e\\- in\u003cbr\u003e\\- description\u003cbr\u003e\\- required\u003cbr\u003e\\- schema                                                   | [parameters-object](https://www.asyncapi.com/docs/specifications/2.0.0#parametersObject) |\n| subscribe   | - operationId\u003cbr\u003e\\- summary\u003cbr\u003e\\- description\u003cbr\u003e\\- message\u003cbr\u003e\\- traits\u003cbr\u003e\\- tags                             | [operation-object](https://www.asyncapi.com/docs/specifications/2.0.0#operationObject) |\n| publish     | - operationId\u003cbr\u003e\\- summary\u003cbr\u003e\\- description\u003cbr\u003e\\- message\u003cbr\u003e\\- traits\u003cbr\u003e\\- tags                             | [operation-object](https://www.asyncapi.com/docs/specifications/2.0.0#operationObject) |\n| messages    | - name\u003cbr\u003e\\- title\u003cbr\u003e\\- summary\u003cbr\u003e\\- description\u003cbr\u003e\\- headers\u003cbr\u003e\\- payload\u003cbr\u003e\\- contentType                | [message-object](https://www.asyncapi.com/docs/specifications/2.0.0#messageObject) |\n| payload     | - description\u003cbr\u003e\\- type\u003cbr\u003e\\- items\u003cbr\u003e\\- properties\u003cbr\u003e\\- format\u003cbr\u003e\\- example\u003cbr\u003e\\- default                  | [schema-object](https://www.asyncapi.com/docs/specifications/2.0.0#schemaObject) |\n| components  | - parameters\u003cbr\u003e\\- messages  \u003cbr\u003e\\- schemas                                                                     | [components-object](https://www.asyncapi.com/docs/specifications/2.0.0#componentsObject) |\n| schema      | - description\u003cbr\u003e\\- type\u003cbr\u003e\\- items\u003cbr\u003e\\- properties\u003cbr\u003e\\- format\u003cbr\u003e\\- example\u003cbr\u003e\\- default                  | [schema-object](https://www.asyncapi.com/docs/specifications/2.0.0#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 asyncapi-format have sorted the AsyncAPI document.\n\n## AsyncAPI filter options\n\nBy specifying the desired filter values for the available filter types, the asyncapi-format CLI will strip out any\nmatching item from the AsyncAPI document. You can combine multiple types to filter out a range of AsyncAPI items.\n\nFor more complex use-cases, we can advise the excellent https://github.com/Mermade/openapi-filter package, which has \nextended options for filtering AsyncAPI documents.\n\n| Type                | Description                               | Type  | Examples                                    |\n|---------------------|-------------------------------------------|-------|---------------------------------------------|\n| operations          | AsyncAPI operations                       | array | ['subscribe','publish']                     |\n| inverseOperations   | AsyncAPI operations that will be kept     | array | ['subscribe','publish']                     |\n| tags                | AsyncAPI tags                             | array | ['measure','command']                       |\n| inverseTags         | AsyncAPI tags that will be kept           | array | ['measure','command']                       |\n| operationIds        | AsyncAPI operation ID's                   | array | ['turnOff','dimLight']                      |\n| inverseOperationIds | AsyncAPI operation ID's that will be kept | array | ['turnOff','dimLight']                      |\n| flags               | Custom flags                              | array | ['x-exclude','x-internal']                  |\n| flagValues          | Custom flags with a specific value        | array | ['x-version: 1.0','x-version: 3.0']         |\n| unusedComponents    | Unused components                         | array | ['examples','schemas']                      |\n| stripFlags          | Custom flags that will be stripped        | array | ['x-exclude','x-internal']                  |\n| textReplace         | Search \u0026 replace values to replace        | array | [{'searchFor':'API','replaceWith':'Event'}] |\n\nSome more details on the available filter types:\n\n### Filter - operations\n\n=\u003e **operations**: Refers to the [Channel Item Object](https://www.asyncapi.com/docs/specifications/2.0.0#channelsObject)\n\nThis will remove all fields and attached fields that match the verbs. In the example below, this would mean that\nall `publish`, `subscribe` items would be removed from the AsyncAPI document.\n\n```yaml\nchannels:\n    smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured:\n        publish:\n            summary: Inform about environmental lighting conditions of a particular streetlight.\n            operationId: receiveLightMeasurement\n            traits:\n                - $ref: '#/components/operationTraits/kafka'\n            message:\n                $ref: '#/components/messages/lightMeasured'\n        subscribe:\n            operationId: turnOn\n            traits:\n                - $ref: '#/components/operationTraits/kafka'\n            message:\n                $ref: '#/components/messages/turnOnOff'\n```\n\n=\u003e **inverseOperations**: This option does the inverse filtering, by keeping only the operations defined and remove all other operations.\n\n### Filter - tags\n\n=\u003e **tags**: Refers to the \"tags\" field from the [Operation Object](https://www.asyncapi.com/docs/specifications/2.0.0#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 `command` or `measure` would be removed from the AsyncAPI document.\n\nFor example:\n\n```yaml\nasyncapi: 2.0.0\ninfo:\n    title: Streetlights API\n    version: 1.0.0\ntags:\n    - name: command\n      description: Light commands\n    - name: measure\n      description: Measurement data\nchannels:\n  smartylighting.streetlights.measured:\n    description: The topic on which measured values may be produced and consumed.\n    publish:\n        summary: Inform about environmental lighting conditions of a particular streetlight.\n        operationId: receiveLightMeasurement\n        tags:\n            - name: measure\n            - name: command\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://www.asyncapi.com/docs/specifications/2.0.0#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 `turnOff` would be removed from the AsyncAPI document.\n\nFor example:\n\n```yaml\nasyncapi: 2.0.0\ninfo:\n    title: Streetlights API\n    version: 1.0.0\nchannels:\n    smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured:\n        subscribe:\n            operationId: turnOn\n```\n\n=\u003e **inverseOperationIds**: 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 - flags\n\n=\u003e **flags**: Refers to a custom property that can be set on any field in the AsyncAPI 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 AsyncAPI document.\n\nFor example:\n\n```yaml\nasyncapi: 2.0.0\ninfo:\n    title: Streetlights API\n    version: 1.0.0\nchannels:\n    smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured:\n        description: The topic on which measured values may be produced and consumed.\n        x-exclude: true\n        subscribe:\n            operationId: turnOn\n```\n\n### Filter - flagValues\n\n=\u003e **flagValues**: Refers to a flag, custom property which can be set on any field in the AsyncAPI 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 AsyncAPI document.\n\n```yaml\nasyncapi: '2.2.0'\ninfo:\n    title: Streetlights Kafka API\nchannels:\n    smartylighting.streetlights.1.0.event.{streetlightId}.lighting.measured:\n        x-version: 1.0\n```\n\nThe filter option `flagValues` also will remove flags that contain an array of values in the AsyncAPI 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 AsyncAPI document.\n\n```yaml\nasyncapi: '2.2.0'\ninfo:\n    title: Streetlights Kafka API\nchannels:\n    smartylighting.streetlights.1.0.event.{streetlightId}.lighting.measured:\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### Filter - unusedComponents\n\n=\u003e **unusedComponents**: Refers to a list of [reusable component types](https://www.asyncapi.com/docs/specifications/2.0.0#componentsObject), from which unused items will be removed.\n\nThis option allows you to strip the AsyncAPI document from any unused items of the targeted `components` types.\nAny item in the list of AsyncAPI `components` that is not referenced as `$ref`, will get marked and removed from the AsyncAPI 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- messages\n- parameters\n- messageTraits\n- operationTraits\n\n### Filter - textReplace\n\n=\u003e **textReplace**: \"search \u0026 replace\" option to replace text in the AsyncAPI specification\n\nThe `textReplace` provides a \"search \u0026 replace\" method, that will search for a text/word/characters in the AsyncAPI description, summary, URL fields and replace it with another text/word/characters.\nThis is very useful to replace data in the AsyncAPI specification.\n\nA `textReplace` example:\n\n```yaml\ntextReplace:\n    - searchFor: 'DummyLighting'\n      replaceWith: 'Smartylighting'\n    - searchFor: 'apiasync.com/'\n      replaceWith: 'asyncapi.com/'\n```\n\nThis will replace all \"DummyLighting\" with \"Smartylighting\" \u0026 \"apiasync.com/\" with \"asyncapi.com/\" in the AsyncAPI 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 AsyncAPI 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 AsyncAPI document.\n\nExample before:\n\n```yaml\nasyncapi: 2.0.0\ninfo:\n    title: Streetlights API\n    version: 1.0.0\nchannels:\n    smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured:\n        description: The topic on which measured values may be produced and consumed.\n        x-exclude: true\n        subscribe:\n            operationId: turnOn\n```\n\nExample after:\n\n```yaml\nasyncapi: 2.0.0\ninfo:\n    title: Streetlights API\n    version: 1.0.0\nchannels:\n    smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured:\n        description: The topic on which measured values may be produced and consumed.\n        subscribe:\n            operationId: turnOn\n```\n\n## AsyncAPI formatting configuration options\n\nThe asyncapi-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 AsyncAPI document.\nThe desired casing can be defined per AsyncAPI key/element (see list below).\nThe keys that are not specified will keep their casing like it is in the original AsyncAPI document, so only for defined fields, the casing will be changed.\n\n| Key                        | Description                                                                               | AsyncAPI reference                                                         |\n| -------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| channels                   | Changes key/name of the channels                                                          | [channels-object](https://www.asyncapi.com/docs/specifications/v2.2.0#channelsObject)|\n| operationId                | Changes operation ID's that are part of the Operations Object                             | [operation-object](https://www.asyncapi.com/docs/specifications/v2.2.0#operationObject)|\n| properties                 | Changes property keys of the schemas of the inline messages, payload \u0026 components         | [schemaObject](https://www.asyncapi.com/docs/specifications/v2.2.0#schemaObject) |\n| componentsSchemas          | Changes the key of the schema models in the components sections \u0026 \"$ref\" links            | [components-object](https://www.asyncapi.com/docs/specifications/v2.2.0#componentsObject) |\n| componentsMessages         | Changes the key of the messages models in the components sections \u0026 \"$ref\" links          | [components-object](https://www.asyncapi.com/docs/specifications/v2.2.0#componentsObject) |\n| componentsParameters       | Changes the key of the parameters models in the components sections \u0026 \"$ref\" links        | [components-object](https://www.asyncapi.com/docs/specifications/v2.2.0#componentsObject) |\n| componentsMessageTraits    | Changes the key of the message traits models in the components sections \u0026 \"$ref\" links    | [components-object](https://www.asyncapi.com/docs/specifications/v2.2.0#componentsObject) |\n| componentsOperationTraits  | Changes the key of the operation traits models in the components sections \u0026 \"$ref\" links  | [components-object](https://www.asyncapi.com/docs/specifications/v2.2.0#componentsObject) |\n| componentsSecuritySchemes  | Changes the key of the security schemes in the components sections \u0026 \"$ref\" links         | [components-object](https://www.asyncapi.com/docs/specifications/v2.2.0#componentsObject) |\n\n### Casing options\n\n| Casing type      | Casing alias | Description                                       | Example           |\n| -----------------| ------------ | ------------------------------------------------- | ----------------- |\n| 🐪 camelCase     | camelCase    | converts a strings to `camelCase`                 | `asyncapiFormat`  |\n| 👨‍🏫 PascalCase    | PascalCase   | converts a strings to `PascalCase`                | `AsyncapiFormat`  |\n| 🥙 kebab-case    | kebabCase    | converts a strings to `kebab-case`                | `asyncapi-format` |\n| 🚂 Train-Case    | TrainCase    | converts a strings to `Train-Case`                | `Asyncapi-Format` |\n| 🐍 snake_case    | snakeCase    | converts a strings to `snake_case`                | `asyncapi_format` |\n| 🕊 Ada_Case      | AdaCase      | converts a strings to `Ada_Case`                  | `Asyncapi_Format` |\n| 📣 CONSTANT_CASE | constantCase | converts a strings to `CONSTANT_CASE`             | `ASYNCAPI_FORMAT` |\n| 👔 COBOL-CASE    | cobolCase    | converts a strings to `COBOL-CASE`                | `ASYNCAPI-FORMAT` |\n| 📍 Dot.notation  | dotNotation  | converts a strings to `Dot.notation`              | `asyncapi.format` |\n| 🛰 Space case    | spaceCase    | converts a strings to `Space case` (with spaces)  | `asyncapi format` |\n| 🏛 Capital Case  | capitalCase  | converts a strings to `Capital Case` (with spaces)| `Asyncapi Format` |\n| 🔡 lower case    | lowerCase    | converts a strings to `lower case` (with spaces)  | `asyncapi format` |\n| 🔠 UPPER CASE    | upperCase    | converts a strings to `UPPER CASE` (with spaces)  | `ASYNCAPI FORMAT` |\n\n\u003e REMARK: All special characters are stripped during conversion, except for the `@` and `$`.\n\nThe casing options are provided by the nano NPM [case-anything](https://github.com/mesqueeb/case-anything) package.\n\n### Format casing - channels\n\n=\u003e **channels**: Refers to the `channels` elements in the AsyncAPI document.\n\nFormatting casing example:\n\n```yaml\nchannels: snake_case\n```\n\nExample before:\n\n```yaml\nchannels:\n  smartylighting.streetlights.lighting.measured:\n    description: The topic on which measured values may be produced and consumed.\n    subscribe:\n      operationId: measuredStreetlight\n```\n\nasyncapi-format will format the \"measuredStreetlight\" from the original dot.notation to snake_case.\n\nExample after:\n\n```yaml\nchannels:\n  smartylighting_streetlights_lighting_measured:\n    description: The topic on which measured values may be produced and consumed.\n    subscribe:\n        operationId: measuredStreetlight\n```\n\n### Format casing - operationId\n\n=\u003e **operationId**: Refers to the `operationId` properties in the AsyncAPI document.\n\nFormatting casing example:\n\n```yaml\noperationId: kebab-case\n```\n\nExample before:\n\n```yaml\nchannels:\n  smartylighting.streetlights.lighting.measured:\n    description: The topic on which measured values may be produced and consumed.\n    subscribe:\n      operationId: measuredStreetlight\n```\n\nasyncapi-format will format the \"measuredStreetlight\" from the original camelcase to kebab-case.\n\nExample after:\n\n```yaml\nchannels:\n  smartylighting.streetlights.lighting.measured:\n    description: The topic on which measured values may be produced and consumed.\n    subscribe:\n      operationId: measured-streetlight\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 channels and the models in the components section of the AsyncAPI document.\n\nFormatting casing example:\n\n```yaml\nproperties: snake_case\n```\n\nExample before:\n\n```yaml\ncomponents:\n  schemas:\n    lightMeasuredPayload:\n      type: object\n      properties:\n        lumensIntensity:\n          type: integer\n          minimum: 0\n          description: Light intensity measured in lumens.\n        sentAt:\n          $ref: '#/components/schemas/sentAt'\n```\n\nThe CLI will format all the properties like: \"lumens\", \"sentAt\" from the original camelcase to snake_case.\n\nExample after:\n\n```yaml\ncomponents:\n  schemas:\n    lightMeasuredPayload:\n      type: object\n      properties:\n          lumens_intensity:\n          type: integer\n          minimum: 0\n          description: Light intensity measured in lumens.\n        sent_at:\n          $ref: '#/components/schemas/sentAt'\n```\n\n### Format casing - component keys\n\n=\u003e **componentsSchemas / componentsMessages / componentsParameters / componentsMessageTraits / componentsOperationTraits / componentsSecuritySchemes**: Refers to all the model objects that are defined in the components section of the AsyncAPI document.\n\nFormatting casing example:\n\n```yaml\ncomponentsSchemas: PascalCase\n```\n\nExample before:\n\n```yaml\nchannels:\n  smartylighting.streetlights.lighting.measured:\n    description: The topic on which measured values may be produced and consumed.\n    subscribe:\n      message:\n        $ref: '#/components/messages/turnOnOff'\ncomponents:\n  messages:\n    lightMeasured:\n      name: lightMeasured\n      title: Light measured\n    turnOnOff:\n      name: turnOnOff\n      title: Turn on/off\n    dimLight:\n        name: dimLight\n        title: Dim light\n```\n\nasyncapi-format will format all the component keys like: \"lightMeasured\", \"turnOnOff\", \"dimLight\" to PascalCase, including formatting all the \"$ref\" used in the AsyncAPI document.\n\nExample after:\n\n```yaml\nchannels:\n  smartylighting.streetlights.lighting.measured:\n    description: The topic on which measured values may be produced and consumed.\n    subscribe:\n      message:\n        $ref: '#/components/messages/TurnOnOff'\ncomponents:\n  messages:\n    LightMeasured:\n      name: lightMeasured\n      title: Light measured\n    TurnOnOff:\n      name: turnOnOff\n      title: Turn on/off\n    DimLight:\n        name: dimLight\n        title: Dim light\n```\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$ asyncapi-format asyncapi.json -o asyncapi-formatted.json\n```\n\n- Format an AsyncAPI document with the default sorting and saves it as a new YAML file\n\n```shell\n$ asyncapi-format asyncapi.yaml -o asyncapi-formatted.yaml\n```\n\n- Format an AsyncAPI document with the default sorting and output it as JSON to STDOUT\n\n```shell\n$ asyncapi-format asyncapi.json --json\n```\n\n- Format an AsyncAPI document with the default sorting and output it as YAML to STDOUT\n\n```shell\n$ asyncapi-format asyncapi.json --yaml\n```\n\n- Format an AsyncAPI JSON document with the default sorting and save it as YAML\n\n```shell\n$ asyncapi-format asyncapi.json -o asyncapi.yaml\n```\n\n- Format an AsyncAPI document but skip the sorting and save it as a new JSON file\n\n```shell\n$ asyncapi-format asyncapi.json -o asyncapi-formatted.json --no-sort\n```\n\nThis should keep the AsyncAPI fields in the same order. This can be needed, when you only want to do a filtering or\nrename action.\n\n- Format an AsyncAPI document, including sorting all elements in the components section\n\n```shell\n$ asyncapi-format asyncapi.json -o asyncapi-formatted.json --sortComponentsFile ./test/json-sort-components/customSortComponents.json\n```\n\nThis will sort all elements in the components ( components/schemas, components/messages, components/parameters,\ncomponents/securitySchemes, ...) section by alphabet.\n\n\n## CLI filter usage\n\n- Format an AsyncAPI document by filtering fields, default sorting and saves it as a new file\n\nWhen you want to strip certain flags, tags, operations, operationID's, you can pass a `filterFile` which contains the\nspecific values for the flags, tags, operations, operationID's.\n\nThis can be useful to combine with the sorting, to end-up with an order and filtered AsyncAPI document.\n\nexample:\n\n```shell\n$ asyncapi-format asyncapi.json -o asyncapi-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    - dimLight\n    - turnOff\n```\n\n## CLI rename usage\n\n- Format an AsyncAPI 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 AsyncAPI 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$ asyncapi-format asyncapi.json -o asyncapi.json --rename \"Streetlights API - AsyncAPI 2.0\"\n```\n\nwhich results in\n\n- before\n\n```json\n{\n    \"asyncapi\": \"2.0.0\",\n    \"info\": {\n        \"title\": \"Streetlights API\",\n```\n\n- after\n\n```json\n{\n    \"asyncapi\": \"2.0.0\",\n    \"info\": {\n        \"title\": \"Streetlights API - AsyncAPI 2.0\",\n```\n\n## CLI configuration usage\n\nAll the CLI options can be managed in a separate configuration file and passed along the asyncapi-format command. This\nwill make configuration easier, especially in CI/CD implementations where the configuration can be stored in version\ncontrol systems.\n\nexample:\n\n```shell\n$ asyncapi-format asyncapi.json --configFile asyncapi-format-options.json\n```\n\nThe formatting will happen based on all the options set in the `asyncapi-format-options.json` file. All the\navailable [AsyncAPI format options](https://github.com/thim81/asyncapi-format#asyncapi-format-cli-options) can be used in\nthe config file.\n\n## OpenAPI documents\n\nFor handling OpenAPI documents, we have created a separate \npackage [openapi-format](https://github.com/thim81/openapi-format) to allow customisation specific for OpenAPI\nuse-cases.\n\n## Credits\n\nThe filter capabilities from `asyncapi-format` are a light version grounded 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 `asyncapi-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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthim81%2Fasyncapi-format","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthim81%2Fasyncapi-format","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthim81%2Fasyncapi-format/lists"}