diff --git a/.claude/skills/add-oas-version.md b/.claude/skills/add-oas-version.md index ea3abbd58..52218e0cc 100644 --- a/.claude/skills/add-oas-version.md +++ b/.claude/skills/add-oas-version.md @@ -1,7 +1,7 @@ # Add OpenAPI/Swagger Version Support **Skill Name:** `add-oas-version` -**Purpose:** Guide the process of adding support for a new OpenAPI/Swagger specification version to swagger-js +**Purpose:** Guide the process of adding support for a new OpenAPI/Swagger specification version to swagger-client **Based on:** Analysis of OAS 3.1.0 implementation (commits ace708ac through 56df8f61) ## Overview @@ -10,7 +10,7 @@ This skill provides a systematic approach to adding support for a new OpenAPI/Sw ## Background: How OAS 3.1.0 Support Was Added -OpenAPI 3.1.0 support was added to swagger-js between December 2022 and January 2023. The implementation introduced a fundamentally new approach using the ApiDOM library ecosystem instead of the legacy SpecMap resolution engine. +OpenAPI 3.1.0 support was added to swagger-client between December 2022 and January 2023. The implementation introduced a fundamentally new approach using the ApiDOM library ecosystem instead of the legacy SpecMap resolution engine. ### Key Implementation Details @@ -210,7 +210,7 @@ class OpenAPIJsonXYParser extends Parser { **3.3 Implement HTTP Resolver** -Create a custom HTTP resolver using swagger-js HTTP client: +Create a custom HTTP resolver using swagger-client HTTP client: `src/helpers/{library}/reference/resolve/resolvers/http-swagger-client/index.js`: ```javascript @@ -221,7 +221,7 @@ class HTTPResolverSwaggerClient extends Resolver { } async resolve(uri) { - // Use swagger-js HTTP client with interceptors + // Use swagger-client HTTP client with interceptors const response = await http({ url: uri, timeout: this.timeout, @@ -234,7 +234,7 @@ class HTTPResolverSwaggerClient extends Resolver { **3.4 Implement Dereference Strategy** -Create custom dereference strategy with swagger-js specific behavior: +Create custom dereference strategy with swagger-client specific behavior: `src/helpers/{library}/reference/dereference/strategies/openapi-X-Y-swagger-client/index.js`: ```javascript @@ -981,7 +981,7 @@ Update project overview: ```markdown ## Project Overview -**swagger-js** supports: +**swagger-client** supports: - OpenAPI X.Y.0 (latest) - OpenAPI 3.1.0 - OpenAPI 3.0.x @@ -1276,7 +1276,7 @@ Closes #ISSUE_NUMBER ### Resolution - [x] New resolver strategy `openapi-X-Y-{library}` -- [x] Custom HTTP resolver using swagger-js HTTP client +- [x] Custom HTTP resolver using swagger-client HTTP client - [x] OpenAPI X.Y specific JSON/YAML parsers - [x] Custom dereference strategy - [x] Normalization plugins @@ -1520,7 +1520,7 @@ After the PR is merged: - OpenAPI Specification: https://spec.openapis.org/ - ApiDOM Documentation: https://github.com/swagger-api/apidom -- SpecMap Library: Internal to swagger-js +- SpecMap Library: Internal to swagger-client - Conventional Commits: https://www.conventionalcommits.org/ --- @@ -1539,4 +1539,4 @@ If you encounter any issues or have questions: **Skill Version:** 1.0 **Last Updated:** 2026-01-23 -**Maintained By:** swagger-js maintainers \ No newline at end of file +**Maintained By:** swagger-client maintainers diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index 4803fc1bd..6bae115a5 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -41,7 +41,7 @@ jobs: run: npm test env: CI: true - - name: Build swagger-js + - name: Build swagger-client run: npm run build - name: Upload commonjs build artifacts if: startsWith(matrix.node-version, '24') diff --git a/CLAUDE.md b/CLAUDE.md index a30f7b89f..2480e5251 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,10 +1,10 @@ -# CLAUDE.md - AI Assistant Guide for swagger-js +# CLAUDE.md - AI Assistant Guide for swagger-client -This document provides comprehensive guidance for AI assistants working on the swagger-js (swagger-client) codebase. +This document provides comprehensive guidance for AI assistants working on the swagger-client codebase. ## Project Overview -**swagger-js** (npm package: `swagger-client`) is a JavaScript module that allows you to fetch, resolve, and interact with Swagger/OpenAPI documents. It supports: +**swagger-client** is a JavaScript module that allows you to fetch, resolve, and interact with Swagger/OpenAPI documents. It supports: - OpenAPI 3.2.0 (latest) - OpenAPI 3.1.0 - OpenAPI 3.0.x (3.0.0 through 3.0.4) @@ -18,7 +18,7 @@ The library is used by Swagger-UI and other tools in the OpenAPI ecosystem to pa ## Repository Structure ``` -swagger-js/ +swagger-client/ ├── src/ # Source code (ES6+ modules) │ ├── execute/ # Request execution logic for OAS operations │ │ ├── oas3/ # OpenAPI 3.x execution diff --git a/NOTICE b/NOTICE index 3a36c4778..8cf5f0a92 100644 --- a/NOTICE +++ b/NOTICE @@ -1,2 +1,2 @@ -swagger-js/swagger-client +swagger-client Copyright 2020-2021 SmartBear Software Inc. diff --git a/README.md b/README.md index 0629e0496..0d5e04127 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,19 @@ # Swagger Client -[![Build Status](https://github.com/swagger-api/swagger-js/actions/workflows/nodejs.yml/badge.svg)](https://github.com/swagger-api/swagger-js/actions) +[![Build Status](https://github.com/swagger-api/swagger-client/actions/workflows/nodejs.yml/badge.svg)](https://github.com/swagger-api/swagger-client/actions) **Swagger Client** is a JavaScript module that allows you to fetch, resolve, and interact with Swagger/OpenAPI documents. ## New! -**This is the new version of swagger-js, 3.x.** The new version supports Swagger 2.0 as well as OpenAPI 3. +**This is the new version of Swagger Client, 3.x.** The new version supports Swagger 2.0 as well as OpenAPI 3. Want to learn more? Check out our [FAQ](docs/migration/migration-2-x-to-3-x.md). For features known to be missing from 3.x please see the [Graveyard](docs/migration/graveyard-3-x.md). -For the older version of swagger-js, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-js/tree/2.x). - -> *The npm package is called `swagger-client` and the GitHub repository is `swagger-js`. -We'll be consolidating that soon. Just giving you the heads-up. You may see references to both names.* +For the older version of Swagger Client, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-client/tree/2.x). ## Compatibility The OpenAPI Specification has undergone multiple revisions since initial creation in 2010. @@ -24,11 +21,11 @@ Compatibility between Swagger Client and the OpenAPI Specification is as follows Swagger Client Version | Release Date | OpenAPI Spec compatibility | Notes ------------------ |--------------|---------------------------------------------------------| ----- -3.37.x | 2026-02-27 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.2.0 | [tag v3.37.0](https://github.com/swagger-api/swagger-js/releases/tag/v3.37.0) -3.33.x | 2024-12-30 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0 | [tag v3.33.0](https://github.com/swagger-api/swagger-js/releases/tag/v3.33.0) -3.19.x | 2023-01-23 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0 | [tag v3.19.0-alpha.3](https://github.com/swagger-api/swagger-js/releases/tag/v3.19.0-alpha.3) -3.10.x | 2020-01-17 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3 | [tag v3.10.0](https://github.com/swagger-api/swagger-js/tree/v3.10.0) -2.1.32 | 2017-01-12 | 1.0, 1.1, 1.2 | [tag v2.1.32](https://github.com/swagger-api/swagger-js/tree/v2.1.32). This [release](https://github.com/swagger-api/swagger-js/releases/tag/v2.1.32) is only available on GitHub. +3.37.x | 2026-02-27 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.2.0 | [tag v3.37.0](https://github.com/swagger-api/swagger-client/releases/tag/v3.37.0) +3.33.x | 2024-12-30 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0 | [tag v3.33.0](https://github.com/swagger-api/swagger-client/releases/tag/v3.33.0) +3.19.x | 2023-01-23 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0 | [tag v3.19.0-alpha.3](https://github.com/swagger-api/swagger-client/releases/tag/v3.19.0-alpha.3) +3.10.x | 2020-01-17 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3 | [tag v3.10.0](https://github.com/swagger-api/swagger-client/tree/v3.10.0) +2.1.32 | 2017-01-12 | 1.0, 1.1, 1.2 | [tag v2.1.32](https://github.com/swagger-api/swagger-client/tree/v2.1.32). This [release](https://github.com/swagger-api/swagger-client/releases/tag/v2.1.32) is only available on GitHub. ## Anonymized analytics diff --git a/docs/development/setting-up.md b/docs/development/setting-up.md index cd277d66b..a22716b17 100644 --- a/docs/development/setting-up.md +++ b/docs/development/setting-up.md @@ -16,8 +16,8 @@ If you use [nvm](https://github.com/nvm-sh/nvm), running following command insid #### Setup steps -1. `git clone https://github.com/swagger-api/swagger-js.git` -2. `cd swagger-js` +1. `git clone https://github.com/swagger-api/swagger-client.git` +2. `cd swagger-client` 3. `npm install` 4. `npm run build` 5. `npm run test` @@ -32,14 +32,14 @@ This section will guide you through how to do that. You'll find complete information about how to do that in swagger-ui [Setting up documentation](https://github.com/swagger-api/swagger-ui/blob/main/docs/development/setting-up.md). -**2. Clone and install swagger-js repository** +**2. Clone and install swagger-client repository** You'll find complete information about how to do that in [Steps](setting-up.md#steps) section of this document. **3. Link repositories using npm link** ```shell script - $ cd /path/to/swagger-js + $ cd /path/to/swagger-client $ npm run build $ npm link $ cd /path/to/swagger-ui @@ -68,7 +68,7 @@ in your favorite editor and return back the `"predev": "npm install"` script. $ cd /path/to/swagger-ui $ npm unlink --no-save swagger-client $ npm install - $ cd /path/to/swagger-js + $ cd /path/to/swagger-client $ npm unlink ``` diff --git a/docs/migration/migration-2-x-to-3-x.md b/docs/migration/migration-2-x-to-3-x.md index 696ede778..e0ac10e6f 100644 --- a/docs/migration/migration-2-x-to-3-x.md +++ b/docs/migration/migration-2-x-to-3-x.md @@ -121,7 +121,7 @@ client.clientAuthorizations.add('cookie', new CookieAuthorization('one=two')) Currently you'd use... > *__NOTE:__ We're working on changing this to be friendlier to use and to support the config file interface.* -> *See: https://github.com/swagger-api/swagger-js/issues/971* +> *See: https://github.com/swagger-api/swagger-client/issues/971* ```javascript Swagger('http://petstore.swagger.io/v2/swagger.json', { diff --git a/docs/usage/http-client-for-oas-operations.md b/docs/usage/http-client-for-oas-operations.md index f0d38ca49..23ba05d37 100644 --- a/docs/usage/http-client-for-oas-operations.md +++ b/docs/usage/http-client-for-oas-operations.md @@ -17,7 +17,7 @@ Property | Description `pathName` | `String`. OpenAPI defines a unique operation as a combination of a path and an HTTP method. If `operationId` is not provided, this property must be set. `method` | `String=["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH"]`. OpenAPI defines a unique operation as a combination of a path and an HTTP method. If `operationId` is not provided, this property must be set. `parameters` | `Object`. Parameters object, eg: `{ q: 'search string' }`. Parameters not defined in `spec` will be ignored. -`parameterBuilders` | `Object=null`. When provided in shape of `{ body: Function, header: Function, query: Function, path: Function, formData: Function }`, it can fully conltrol how parameters of various types are built. This library comes with two default parameter builders: [OpenAPI 2.x builders](https://github.com/swagger-api/swagger-js/blob/main/src/execute/swagger2/parameter-builders.js) and [OpenAPI 3.0.x builders](https://github.com/swagger-api/swagger-js/blob/main/src/execute/oas3/parameter-builders.js). +`parameterBuilders` | `Object=null`. When provided in shape of `{ body: Function, header: Function, query: Function, path: Function, formData: Function }`, it can fully control how parameters of various types are built. This library comes with two default parameter builders: [OpenAPI 2.x builders](https://github.com/swagger-api/swagger-client/blob/main/src/execute/swagger2/parameter-builders.js) and [OpenAPI 3.0.x builders](https://github.com/swagger-api/swagger-client/blob/main/src/execute/oas3/parameter-builders.js). `securities` | `Object`. Maps security schemes to a request. Securities not defined in `spec` will be ignored.

*Examples*

*Bearer:* `{ authorized: { BearerAuth: {value: "3492342948239482398"} } }`

*Basic:* `{ authorized: { BasicAuth: { username: 'login', password: 'secret' } } }`

*ApiKey:* `{ authorized: { ApiKey: { value: '234934239' } } }`

*oAuth2:* `{ authorized: { oAuth2: { token: { access_token: '234934239' } } } }` `requestInterceptor` | `Function=identity`. Either synchronous or asynchronous function transformer that accepts `Request` and should return `Request`. `responseInterceptor` | `Function=identity`. Either synchronous or asynchronous function transformer that accepts `Response` and should return `Response`. diff --git a/docs/usage/tags-interface.md b/docs/usage/tags-interface.md index d9f65fc2c..8c806e900 100644 --- a/docs/usage/tags-interface.md +++ b/docs/usage/tags-interface.md @@ -101,7 +101,7 @@ Option | Description `userFetch` | `Function=cross-fetch`. Custom **asynchronous** fetch function that accepts two arguments: the `url` and the `Request` object and must return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object. `skipNormalization` | `Boolean=false`. Normalization creates unique operationIds when explicit operationIds are duplicates, and preserve originals. -> *__Note:__ for more information about [requestInterceptor](http-client.md#request-interceptor), [responseInterceptor](http-client.md#response-interceptor) and [userFetch](https://github.com/swagger-api/swagger-js/blob/main/docs/usage/http-client.md#custom-fetch), please refer to the [HTTP Client](http-client.md) documentation.* +> *__Note:__ for more information about [requestInterceptor](http-client.md#request-interceptor), [responseInterceptor](http-client.md#response-interceptor) and [userFetch](https://github.com/swagger-api/swagger-client/blob/main/docs/usage/http-client.md#custom-fetch), please refer to the [HTTP Client](http-client.md) documentation.* ### Options override diff --git a/package.json b/package.json index 00798f957..7638502c3 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "swagger-client", "version": "3.38.0", - "description": "SwaggerJS - a collection of interfaces for OAI specs", + "description": "Swagger Client - a collection of interfaces for OAI specs", "browser": { "./src/helpers/btoa.node.js": "./src/helpers/btoa.browser.js", "./lib/helpers/btoa.node.js": "./lib/helpers/btoa.browser.js", @@ -14,7 +14,7 @@ "module": "es/index.js", "jsnext:main": "es/index.js", "unpkg": "dist/swagger-client.browser.min.js", - "repository": "git@github.com:swagger-api/swagger-js.git", + "repository": "git@github.com:swagger-api/swagger-client.git", "contributors": [ "(in alphabetical order)", "Anna Bodnia ", diff --git a/src/interfaces.js b/src/interfaces.js index d04ad20bd..0e1ff2eb9 100644 --- a/src/interfaces.js +++ b/src/interfaces.js @@ -11,12 +11,12 @@ export const self = { }; // Make an execute, bound to arguments defined in mapTagOperation's callback (cb) -export function makeExecute(swaggerJs = {}) { +export function makeExecute(swaggerClient = {}) { return ({ pathName, method, operationId }) => (parameters, opts = {}) => { - const { requestInterceptor, responseInterceptor, userFetch } = swaggerJs; - return swaggerJs.execute({ - spec: swaggerJs.spec, + const { requestInterceptor, responseInterceptor, userFetch } = swaggerClient; + return swaggerClient.execute({ + spec: swaggerClient.spec, requestInterceptor, responseInterceptor, userFetch, @@ -33,12 +33,12 @@ export function makeExecute(swaggerJs = {}) { // The shape // { apis: { [tag]: { operations: [operation]: { execute }}}} // NOTE: this is mostly for compatibility -export function makeApisTagOperationsOperationExecute(swaggerJs = {}) { +export function makeApisTagOperationsOperationExecute(swaggerClient = {}) { // { apis: tag: operations: execute } - const cb = self.makeExecute(swaggerJs); + const cb = self.makeExecute(swaggerClient); const tagOperations = self.mapTagOperations({ - v2OperationIdCompatibilityMode: swaggerJs.v2OperationIdCompatibilityMode, - spec: swaggerJs.spec, + v2OperationIdCompatibilityMode: swaggerClient.v2OperationIdCompatibilityMode, + spec: swaggerClient.spec, cb, }); @@ -58,12 +58,12 @@ export function makeApisTagOperationsOperationExecute(swaggerJs = {}) { } // .apis[tag][operationId]:ExecuteFunction interface -export function makeApisTagOperation(swaggerJs = {}) { - const cb = self.makeExecute(swaggerJs); +export function makeApisTagOperation(swaggerClient = {}) { + const cb = self.makeExecute(swaggerClient); return { apis: self.mapTagOperations({ - v2OperationIdCompatibilityMode: swaggerJs.v2OperationIdCompatibilityMode, - spec: swaggerJs.spec, + v2OperationIdCompatibilityMode: swaggerClient.v2OperationIdCompatibilityMode, + spec: swaggerClient.spec, cb, }), }; diff --git a/test/bugs/1719.js b/test/bugs/1719.js index a2ee98114..7fa3afa34 100644 --- a/test/bugs/1719.js +++ b/test/bugs/1719.js @@ -1,4 +1,4 @@ -// https://github.com/swagger-api/swagger-js/issues/1719 +// https://github.com/swagger-api/swagger-client/issues/1719 import path from 'path'; import fs from 'fs'; diff --git a/test/client.js b/test/client.js index 59197f518..729222d27 100644 --- a/test/client.js +++ b/test/client.js @@ -152,7 +152,7 @@ describe('http', () => { }); /** - * See https://github.com/swagger-api/swagger-js/issues/1005 + * See https://github.com/swagger-api/swagger-client/issues/1005 */ test.skip('should get a pet from the petstore', (done) => { Swagger('http://localhost:8000/petstore.json').then((client) => { @@ -168,7 +168,7 @@ describe('http', () => { }); /** - * See https://github.com/swagger-api/swagger-js/issues/1277 + * See https://github.com/swagger-api/swagger-client/issues/1277 */ test('should return a helpful error when the connection is refused', () => Swagger('http://localhost:1/untouchable.yaml') @@ -181,7 +181,7 @@ describe('http', () => { })); /** - * See https://github.com/swagger-api/swagger-js/issues/1002 + * See https://github.com/swagger-api/swagger-client/issues/1002 */ test.skip('should return an error when a spec doesnt exist', (done) => { Swagger('http://localhost:8000/absent.yaml') @@ -194,7 +194,7 @@ describe('http', () => { }); /** - * See https://github.com/swagger-api/swagger-js/issues/1004 + * See https://github.com/swagger-api/swagger-client/issues/1004 */ test.skip('fail with invalid verbs', (done) => { Swagger('http://localhost:8000/invalid-operation.yaml').then((client) => { @@ -206,7 +206,7 @@ describe('http', () => { /** * Loads a spec where the `host` and `schema` are not defined - * See https://github.com/swagger-api/swagger-js/issues/1000 + * See https://github.com/swagger-api/swagger-client/issues/1000 */ test('use the host from whence the spec was fetched', (done) => { Swagger('http://localhost:8000/pathless.yaml') diff --git a/test/helpers/id-from-path-method/index.js b/test/helpers/id-from-path-method/index.js index 1f9565550..9fc44f61e 100644 --- a/test/helpers/id-from-path-method/index.js +++ b/test/helpers/id-from-path-method/index.js @@ -24,7 +24,7 @@ describe('helpers', () => { v2OperationIdCompatibilityMode: true, }); - // https://github.com/swagger-api/swagger-js/issues/1269#issue-309070070 + // https://github.com/swagger-api/swagger-client/issues/1269#issue-309070070 expect(fn('/foo/{bar}/baz', 'get')).toEqual('get_foo_bar_baz'); expect(fn('/one/{foo}/{bar}', 'get')).toEqual('get_one_foo_bar'); expect(fn('/one/{bar}/-----{baz}', 'get')).toEqual('get_one_bar_baz'); diff --git a/test/oas3/execute/build-request.js b/test/oas3/execute/build-request.js index 229370a98..224b44b1e 100644 --- a/test/oas3/execute/build-request.js +++ b/test/oas3/execute/build-request.js @@ -1,4 +1,4 @@ -// https://github.com/swagger-api/swagger-js/issues/1116 +// https://github.com/swagger-api/swagger-client/issues/1116 import { buildRequest } from '../../../src/execute/index.js'; describe('buildRequest - OAS 3.0.x', () => {