feat(openapi): tooling upgrades #1126

erunion · 2024-12-21T05:39:29Z

🧰 Changes

This upgrades our oas and oas-normalize tooling to their latest releases. Included in this work are a couple new features to and refactors to some commands:

`openapi`

The .validate() call within oas-normalize has been refactored to no longer do conversion and validation, the conversion side has been split off to a new .convert() method.

As part of this change the previous convertToLatest parameter that .validate() accepted for converting Swagger definitions to OpenAPI no longer exists anywhere. We had this configurable within some internal methods within rdme but it was never exposed, and converting Swagger to OpenAPI has always been the default behavior throughout rdme.

`openapi inspect`

Our analyzer tool can now surface information on if an API definition utilizes common parameters.¹

I have also removed our dependency on pluralize because we were only loading it to pluralize three strings: "media type", "operation", and "security type". Because these can be easily pluralized with a one-liner we don't really need to import a wholeass library to do this.

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#path-item-object ↩

kanadgupta

a few non-blocking comments below otherwise LGTM!

kanadgupta · 2024-12-29T20:17:08Z

src/lib/prepareOas.ts

    spinner.fail();
    debug(`raw validation error object: ${JSON.stringify(err)}`);
    throw err;
  });
+
+  // If we were supplied a Postman collection this will **always** convert it to OpenAPI 3.0.
+  api = await oas.convert().catch((err: Error) => {


we shouldn't need to do this if we're validating, correct?

We don't, but this thing method seems to always want to return an OpenAPI definition as it's mutating info.title.

src/lib/prepareOas.ts

kanadgupta

this got me thinking about a few issues we should figure out soon, see #1141 and #1142

# [10.1.0-next.1](v10.0.0...v10.1.0-next.1) (2025-01-06) ### Features * **openapi:** tooling upgrades ([#1126](#1126)) ([6678d68](6678d68)) [skip ci]

kanadgupta · 2025-01-06T18:42:14Z

🎉 This PR is included in version 10.1.0-next.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

## 🧰 Changes Before: ``` Package Current Wanted Latest Location Depended by @commitlint/cli 19.6.0 19.6.1 19.6.1 node_modules/@commitlint/cli rdme @oclif/core 4.0.34 4.2.0 4.2.0 node_modules/@oclif/core rdme @oclif/plugin-autocomplete 3.2.11 3.2.16 3.2.16 node_modules/@oclif/plugin-autocomplete rdme @oclif/plugin-help 6.2.18 6.2.20 6.2.20 node_modules/@oclif/plugin-help rdme @oclif/plugin-not-found 3.2.29 3.2.33 3.2.33 node_modules/@oclif/plugin-not-found rdme @oclif/plugin-warn-if-update-available 3.1.24 3.1.29 3.1.29 node_modules/@oclif/plugin-warn-if-update-available rdme @oclif/test 4.1.2 4.1.6 4.1.6 node_modules/@oclif/test rdme @rollup/plugin-commonjs 28.0.1 28.0.2 28.0.2 node_modules/@rollup/plugin-commonjs rdme @rollup/plugin-node-resolve 15.3.0 15.3.1 16.0.0 node_modules/@rollup/plugin-node-resolve rdme @rollup/plugin-replace 6.0.1 6.0.2 6.0.2 node_modules/@rollup/plugin-replace rdme chalk 5.3.0 5.4.1 5.4.1 node_modules/chalk rdme debug 4.3.7 4.4.0 4.4.0 node_modules/debug rdme eslint 8.57.1 8.57.1 9.17.0 node_modules/eslint rdme ignore 6.0.2 6.0.2 7.0.0 node_modules/ignore rdme knip 5.39.0 5.41.1 5.41.1 node_modules/knip rdme nock 14.0.0-beta.18 14.0.0-beta.19 13.5.6 node_modules/nock rdme oas 25.0.4 25.2.1 25.2.1 node_modules/oas rdme oas-normalize 11.1.4 11.1.4 12.0.0 node_modules/oas-normalize rdme oclif 4.16.0 4.17.10 4.17.10 node_modules/oclif rdme prettier 3.4.1 3.4.2 3.4.2 node_modules/prettier rdme rollup 4.28.0 4.30.0 4.30.0 node_modules/rollup rdme table 6.8.2 6.9.0 6.9.0 node_modules/table rdme type-fest 4.29.1 4.31.0 4.31.0 node_modules/type-fest rdme undici 5.28.4 5.28.4 7.2.0 node_modules/undici rdme ``` After: ``` Package Current Wanted Latest Location Depended by eslint 8.57.1 8.57.1 9.17.0 node_modules/eslint rdme nock 14.0.0-beta.19 14.0.0-beta.19 13.5.6 node_modules/nock rdme oas 25.0.4 25.2.1 25.2.1 node_modules/oas rdme oas-normalize 11.1.4 11.1.4 12.0.0 node_modules/oas-normalize rdme undici 5.28.4 5.28.4 7.2.0 node_modules/undici rdme ``` `oas` and `oas-normalize` are being bumped in #1126 --------- Co-authored-by: Jon Ursenbach <jon@ursenba.ch>

This upgrades our [oas](https://npm.im/oas) and [oas-normalize](https://npm.im/oas-normalize) tooling to their latest releases. Included in this work are a couple new features to and refactors to some commands: The `.validate()` call within `oas-normalize` has been refactored to no longer do conversion and validation, the conversion side has been split off to a new `.convert()` method. As part of this change the previous `convertToLatest` parameter that `.validate()` accepted for converting Swagger definitions to OpenAPI no longer exists anywhere. We had this configurable within some internal methods within rdme but it was never exposed, and converting Swagger to OpenAPI has always been the default behavior throughout rdme. Our analyzer tool can now surface information on if an API definition utilizes common parameters.[^1] I have also removed our dependency on [pluralize](https://npm.im/pluralize) because we were only loading it to pluralize three strings: "media type", "operation", and "security type". Because these can be easily pluralized with a one-liner we don't really need to import a wholeass library to do this. [^1]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#path-item-object

* **openapi:** tooling upgrades ([#1126](#1126)) ([6678d68](6678d68)) [skip ci]

## 🧰 Changes Before: ``` Package Current Wanted Latest Location Depended by @commitlint/cli 19.6.0 19.6.1 19.6.1 node_modules/@commitlint/cli rdme @oclif/core 4.0.34 4.2.0 4.2.0 node_modules/@oclif/core rdme @oclif/plugin-autocomplete 3.2.11 3.2.16 3.2.16 node_modules/@oclif/plugin-autocomplete rdme @oclif/plugin-help 6.2.18 6.2.20 6.2.20 node_modules/@oclif/plugin-help rdme @oclif/plugin-not-found 3.2.29 3.2.33 3.2.33 node_modules/@oclif/plugin-not-found rdme @oclif/plugin-warn-if-update-available 3.1.24 3.1.29 3.1.29 node_modules/@oclif/plugin-warn-if-update-available rdme @oclif/test 4.1.2 4.1.6 4.1.6 node_modules/@oclif/test rdme @rollup/plugin-commonjs 28.0.1 28.0.2 28.0.2 node_modules/@rollup/plugin-commonjs rdme @rollup/plugin-node-resolve 15.3.0 15.3.1 16.0.0 node_modules/@rollup/plugin-node-resolve rdme @rollup/plugin-replace 6.0.1 6.0.2 6.0.2 node_modules/@rollup/plugin-replace rdme chalk 5.3.0 5.4.1 5.4.1 node_modules/chalk rdme debug 4.3.7 4.4.0 4.4.0 node_modules/debug rdme eslint 8.57.1 8.57.1 9.17.0 node_modules/eslint rdme ignore 6.0.2 6.0.2 7.0.0 node_modules/ignore rdme knip 5.39.0 5.41.1 5.41.1 node_modules/knip rdme nock 14.0.0-beta.18 14.0.0-beta.19 13.5.6 node_modules/nock rdme oas 25.0.4 25.2.1 25.2.1 node_modules/oas rdme oas-normalize 11.1.4 11.1.4 12.0.0 node_modules/oas-normalize rdme oclif 4.16.0 4.17.10 4.17.10 node_modules/oclif rdme prettier 3.4.1 3.4.2 3.4.2 node_modules/prettier rdme rollup 4.28.0 4.30.0 4.30.0 node_modules/rollup rdme table 6.8.2 6.9.0 6.9.0 node_modules/table rdme type-fest 4.29.1 4.31.0 4.31.0 node_modules/type-fest rdme undici 5.28.4 5.28.4 7.2.0 node_modules/undici rdme ``` After: ``` Package Current Wanted Latest Location Depended by eslint 8.57.1 8.57.1 9.17.0 node_modules/eslint rdme nock 14.0.0-beta.19 14.0.0-beta.19 13.5.6 node_modules/nock rdme oas 25.0.4 25.2.1 25.2.1 node_modules/oas rdme oas-normalize 11.1.4 11.1.4 12.0.0 node_modules/oas-normalize rdme undici 5.28.4 5.28.4 7.2.0 node_modules/undici rdme ``` `oas` and `oas-normalize` are being bumped in #1126 --------- Co-authored-by: Jon Ursenbach <jon@ursenba.ch>

## 🧰 Changes when reviewing #1126, i noticed a few small bugs in our `prepareOas` helper function. this PR makes a few typesafety improvements so we shouldn't run into this issue again(?) ~~one outstanding question that i'd like to figure out prior to merge, see #1142 (**edit**: going to continue bundling and handle this issue in a follow-up PR) ## 🧬 QA & Testing do tests + types pass?

when reviewing #1126, i noticed a few small bugs in our `prepareOas` helper function. this PR makes a few typesafety improvements so we shouldn't run into this issue again(?) ~~one outstanding question that i'd like to figure out prior to merge, see #1142 (**edit**: going to continue bundling and handle this issue in a follow-up PR) do tests + types pass?

## 🧰 Changes reapplies the following changes from the `next` branch onto the `v9` branch: - [x] #1124 - [x] #1125 - [x] #1126 - [x] #1127 - [x] #1143 - [x] #1144 - [x] #1141 ## 🧬 QA & Testing do tests pass? --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Jon Ursenbach <erunion@users.noreply.github.com> Co-authored-by: semantic-release-bot <semantic-release-bot@martynus.net> Co-authored-by: Jon Ursenbach <jon@ursenba.ch> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

# [10.1.0](v10.0.0...v10.1.0) (2025-01-14) ### Bug Fixes * **openapi:** type fixes in `prepareOas` ([#1141](#1141)) ([fc55d28](fc55d28)) ### Features * **openapi:** a fresh coat of paint on `openapi inspect` ([#1127](#1127)) ([ff8c304](ff8c304)) * **openapi:** tooling upgrades ([#1126](#1126)) ([6678d68](6678d68)) * **v9:** backport openapi tooling etc. from v10 ([#1145](#1145)) ([14828db](14828db)) [skip ci]

kanadgupta · 2025-01-14T18:18:06Z

🎉 This PR is included in version 10.1.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

feat(openapi): oas tooling upgrades

eec3c57

erunion added enhancement New feature or request dependencies Pull requests that update a dependency file command:openapi Issues pertaining to the `openapi`, `validate`, `reduce`, or `swagger` commands labels Dec 21, 2024

erunion requested a review from kanadgupta December 21, 2024 05:39

kanadgupta approved these changes Dec 29, 2024

View reviewed changes

chore: pr feedback

08604ae

erunion requested a review from kanadgupta January 3, 2025 18:17

This was referenced Jan 6, 2025

fix(openapi): type fixes in prepareOas #1141

Merged

chore(deps): bump #1143

Merged

kanadgupta approved these changes Jan 6, 2025

View reviewed changes

kanadgupta mentioned this pull request Jan 6, 2025

chore(deps): bump oas from 25.0.4 to 25.2.1 #1136

Closed

erunion merged commit 6678d68 into next Jan 6, 2025
8 checks passed

erunion deleted the feat/openapi-tooling-upgrades branch January 6, 2025 18:39

kanadgupta pushed a commit that referenced this pull request Jan 6, 2025

build(release): 🚀 v10.1.0-next.1 🦉

fb1f8ba

# [10.1.0-next.1](v10.0.0...v10.1.0-next.1) (2025-01-06) ### Features * **openapi:** tooling upgrades ([#1126](#1126)) ([6678d68](6678d68)) [skip ci]

kanadgupta added the released on @next label Jan 6, 2025

kanadgupta pushed a commit that referenced this pull request Jan 6, 2025

build(release): 🚀 v10.1.0-next.1 🦉

fd4715c

* **openapi:** tooling upgrades ([#1126](#1126)) ([6678d68](6678d68)) [skip ci]

kanadgupta mentioned this pull request Jan 6, 2025

feat(v9): backport openapi tooling etc. from v10 #1145

Merged

7 tasks

kanadgupta added the released label Jan 14, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(openapi): tooling upgrades #1126

feat(openapi): tooling upgrades #1126

erunion commented Dec 21, 2024 •

edited

Loading

kanadgupta left a comment

kanadgupta Dec 29, 2024

erunion Jan 3, 2025

kanadgupta left a comment

kanadgupta commented Jan 6, 2025

kanadgupta commented Jan 14, 2025

feat(openapi): tooling upgrades #1126

feat(openapi): tooling upgrades #1126

Conversation

erunion commented Dec 21, 2024 • edited Loading

🧰 Changes

openapi

openapi inspect

Footnotes

kanadgupta left a comment

Choose a reason for hiding this comment

kanadgupta Dec 29, 2024

Choose a reason for hiding this comment

erunion Jan 3, 2025

Choose a reason for hiding this comment

kanadgupta left a comment

Choose a reason for hiding this comment

kanadgupta commented Jan 6, 2025

kanadgupta commented Jan 14, 2025

erunion commented Dec 21, 2024 •

edited

Loading

`openapi`

`openapi inspect`