Skip to content

Commit 7136230

Browse files
thim81thim81
authored
release 1.31.0 (#207)
* release 1.31.0 * test: Add additional coverage for addQuotesToRefInString
1 parent 692fb3f commit 7136230

5 files changed

Lines changed: 109 additions & 73 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
## unreleased
22

3+
## [1.31.0] - 2026-04-12
4+
5+
- refactor: replace stoplight/yaml with yaml (eemeli) (#206)
6+
37
## [1.30.1] - 2026-03-26
48

59
- CLI: Fix normalize YAML block scalar newlines (#202)

‎package-lock.json‎

Lines changed: 31 additions & 31 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
},
3939
"dependencies": {
4040
"yaml": "^2.8.3",
41-
"api-ref-bundler": "^0.5.0",
41+
"api-ref-bundler": "^0.5.1",
4242
"case-anything": "2.1.10",
4343
"jsonpathly": "^3.0.0",
4444
"neotraverse": "^0.6.18"

‎readme.md‎

Lines changed: 37 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ To quickly standardize OpenAPI documents there is support for generating the ope
1616
The CLI can split large OpenAPI documents into modular, multi-file structures for easier management.
1717
For upgrades, the openapi-format CLI offers the option to convert an OpenAPI 3.0 or 3.1 document to OpenAPI 3.1 or 3.2.
1818

19-
With the newly added OpenAPI Overlay support, users can overlay changes onto existing OpenAPI documents, to extend and customize the OpenAPI document.
19+
With the OpenAPI Overlay support, users can overlay changes onto existing OpenAPI documents, to extend and customize the OpenAPI document.
2020

2121
## Table of content
2222
* [Use-cases](#use-cases)
@@ -67,15 +67,15 @@ Postman collections, test suites, ...
6767
- [x] Order OpenAPI fields in a default order
6868
- [x] Order OpenAPI fields in a custom order
6969
- [x] Order Components elements by alphabet
70-
- [x] Format the casing (camelCase,PascalCase, ...) of component elements
7170
- [x] Filter OpenAPI files based on methods
7271
- [x] Filter OpenAPI files based on flags
7372
- [x] Filter OpenAPI files based on flags values
7473
- [x] Filter OpenAPI files based on tags
7574
- [x] Filter OpenAPI files based on operationID's
7675
- [x] Filter OpenAPI files based on operations definition
7776
- [x] Filter OpenAPI files based on response content-types
78-
- [x] Apply OpenAPI overlay actions
77+
- [x] Format the casing (camelCase,PascalCase, ...) of component elements
78+
- [x] Apply OpenAPI Overlay actions
7979
- [x] Strip flags from OpenAPI files
8080
- [x] Strip unused components from OpenAPI files
8181
- [x] Generate OpenAPI elements for consistency
@@ -89,7 +89,6 @@ Postman collections, test suites, ...
8989
- [x] Format via CLI
9090
- [x] Format via local or remote config files
9191
- [x] Use as a Module
92-
- [x] Aligned YAML parsing style with Stoplight Studio style
9392
- [x] Support for OpenAPI 3.0
9493
- [x] Support for OpenAPI 3.1
9594
- [x] Support for OpenAPI 3.2
@@ -112,46 +111,37 @@ More info about the playground features and usage can be found on the [website](
112111

113112
## Installation
114113

115-
### Local Installation (recommended)
114+
### NPX usage (recommended)
116115

117-
While possible to install globally, we recommend that you add the openapi-format CLI to the `node_modules` by using:
116+
To execute the CLI without installing it via npm, use the npx method
118117

119118
```shell
120-
$ npm install --save openapi-format
119+
$ npx openapi-format your-openapi-file.yaml
121120
```
122121

123-
or using yarn...
122+
### Local Installation
123+
124+
While possible to install globally, we recommend that you add the openapi-format CLI to the `node_modules` by using:
124125

125126
```shell
126-
$ yarn add openapi-format
127+
$ npm install --save openapi-format
127128
```
128129

129-
Note that this will require you to run the openapi-format CLI with `npx openapi-format your-openapi-file.yaml` or, if
130-
you are using an older versions of npm, `./node_modules/.bin/openapi-format your-openapi-file.yaml`.
131-
132130
### Global Installation
133131

134132
```shell
135133
$ npm install -g openapi-format
136134
```
137135

138-
### NPX usage
139-
140-
To execute the CLI without installing it via npm, use the npx method
141-
142-
```shell
143-
$ npx openapi-format your-openapi-file.yaml
144-
```
145-
146-
### Codex skill usage
136+
### AI (OpenAI Codex/Claude Code/...) skill usage
147137

148138
To install the `openapi-format` skill from this repository:
149139

150140
```shell
151141
$ npx skills add https://github.com/thim81/openapi-format --skill openapi-format
152142
```
153143

154-
Then use it in Codex by explicitly referencing the skill in your prompt, for example:
144+
Then use it in Claude, Codex by explicitly referencing the skill in your prompt, for example:
155145

156146
```text
157147
Using $openapi-format, create a minimal filter config to remove internal endpoints and give me the CLI command.
@@ -243,22 +233,22 @@ the [defaultSort.json](https://github.com/thim81/openapi-format/blob/main/defaul
243233
You can easily modify this by specifying your own ordering per key, which can be passed on to the CLI (see below for an
244234
example on how to do this).
245235

246-
| Key | Ordered by | OpenAPI reference |
247-
| ----------- | ----------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------------------- |
248-
| root | - openapi<br>\- info<br>\- servers<br>\- paths<br>\- components<br>\- tags<br>\- x-tagGroups<br>\- externalDocs | [openapi-object](https://spec.openapis.org/oas/v3.0.3.html#openapi-object) |
249-
| get | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
250-
| post | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
251-
| put | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
252-
| patch | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
253-
| delete | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
254-
| parameters | - name<br>\- in<br>\- description<br>\- required<br>\- schema | [parameterObject](https://spec.openapis.org/oas/v3.0.3.html#parameterObject) |
255-
| requestBody | - description<br>\- headers<br>\- content<br>\- links | [request-body-object](https://spec.openapis.org/oas/v3.0.3.html#request-body-object) |
256-
| responses | - description<br>\- headers<br>\- content<br>\- links | [responses-object](https://spec.openapis.org/oas/v3.0.3.html#responses-object) |
257-
| content | (By alphabet) | [responses-object](https://spec.openapis.org/oas/v3.0.3.html#responses-object) |
258-
| components | - parameters<br>\- schemas | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |
259-
| schema | - description<br>\- type<br>\- items<br>\- properties<br>\- format<br>\- example<br>\- default | [schemaObject](https://spec.openapis.org/oas/v3.0.3.html#schemaObject) |
260-
| schemas | - description<br>\- type<br>\- items<br>\- properties<br>\- format<br>\- example<br>\- default | |
261-
| properties | - description<br>\- type<br>\- items<br>\- format<br>\- example<br>\- default<br>\- enum | |
236+
| Key | Ordered by | OpenAPI reference |
237+
|-------------|-----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
238+
| root | - openapi<br>\- info<br>\- servers<br>\- paths<br>\- components<br>\- tags<br>\- x-tagGroups<br>\- externalDocs | [openapi-object](https://spec.openapis.org/oas/v3.0.3.html#openapi-object) |
239+
| get | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
240+
| post | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
241+
| put | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
242+
| patch | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
243+
| delete | - operationId<br>\- summary<br>\- description<br>\- parameters<br>\- requestBody<br>\- responses | [operationObject](https://spec.openapis.org/oas/v3.0.3.html#operationObject) |
244+
| parameters | - name<br>\- in<br>\- description<br>\- required<br>\- schema | [parameterObject](https://spec.openapis.org/oas/v3.0.3.html#parameterObject) |
245+
| requestBody | - description<br>\- headers<br>\- content<br>\- links | [request-body-object](https://spec.openapis.org/oas/v3.0.3.html#request-body-object) |
246+
| responses | - description<br>\- headers<br>\- content<br>\- links | [responses-object](https://spec.openapis.org/oas/v3.0.3.html#responses-object) |
247+
| content | (By alphabet) | [responses-object](https://spec.openapis.org/oas/v3.0.3.html#responses-object) |
248+
| components | - parameters<br>\- schemas | [components-object](https://spec.openapis.org/oas/v3.0.3.html#components-object) |
249+
| schema | - description<br>\- type<br>\- items<br>\- properties<br>\- format<br>\- example<br>\- default | [schemaObject](https://spec.openapis.org/oas/v3.0.3.html#schemaObject) |
250+
| schemas | - description<br>\- type<br>\- items<br>\- properties<br>\- format<br>\- example<br>\- default | |
251+
| properties | - description<br>\- type<br>\- items<br>\- format<br>\- example<br>\- default<br>\- enum | |
262252

263253
Have 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.
264254

@@ -1699,11 +1689,19 @@ For handling AsyncAPI documents, we have created a separate
16991689
package [asyncapi-format](https://github.com/thim81/asyncapi-format) to allow customisation specific for AsyncAPI
17001690
use-cases.
17011691

1692+
## YAML handling
1693+
1694+
As of `v1.31.0`, `openapi-format` uses `yaml` by [eemeli](https://github.com/eemeli/yaml) instead of `@stoplight/yaml`, thanks to the contribution of [@guilhas07](https://github.com/guilhas07).
1695+
1696+
This improves YAML comment preservation and fixes previous formatting issues where:
1697+
- valid YAML strings were unnecessarily quoted
1698+
- double-quoted strings were converted to single quotes
1699+
17021700
## Credits
17031701

17041702
This package is inspired by
17051703
the [@microsoft.azure/format-spec](https://www.npmjs.com/package/@microsoft.azure/format-spec) from [@fearthecowboy](https://github.com/fearthecowboy). The
1706-
original code was not available on GitHub, with the last update being 3 years ago, so to improve support and extend it we
1704+
original code was not available on GitHub, with the last update since 2018, so to improve support and extend it; we
17071705
tried to reproduce the original functionality.
17081706

17091707
The filter capabilities from `openapi-format` are inspired by the work from [@MikeRalphson](https://github.com/mikeralphson) on

0 commit comments

Comments
 (0)