swagger-client

What is swagger-client?

The swagger-client npm package is a JavaScript client for Swagger/OpenAPI specifications. It allows you to interact with APIs described by Swagger/OpenAPI documents, making it easier to consume and interact with RESTful services.

What are swagger-client's main functionalities?

Initialize Client

This feature allows you to initialize a Swagger client by providing the URL to the Swagger/OpenAPI specification. The client can then be used to interact with the API described by the specification.

const Swagger = require('swagger-client');
const client = new Swagger({ url: 'http://petstore.swagger.io/v2/swagger.json' });

Make API Calls

This feature allows you to make API calls using the initialized client. In this example, the client is used to call the 'getPetById' operation from the Petstore API.

client.then(client => {
  client.apis.pet.getPetById({ petId: 1 }).then(response => {
    console.log(response);
  });
});

Handle Authentication

This feature allows you to handle authentication by providing authorization details when initializing the client. In this example, an API key is provided for authentication.

const client = new Swagger({
  url: 'http://petstore.swagger.io/v2/swagger.json',
  authorizations: {
    api_key: new Swagger.ApiKeyAuthorization('api_key', 'YOUR_API_KEY', 'query')
  }
});

Other packages similar to swagger-client

axios

Axios is a promise-based HTTP client for the browser and Node.js. While it does not specifically target Swagger/OpenAPI specifications, it can be used to make HTTP requests to any API. Compared to swagger-client, axios is more general-purpose and does not provide built-in support for Swagger/OpenAPI documents.

openapi-client-axios

openapi-client-axios is a package that combines the capabilities of Axios with OpenAPI specifications. It allows you to generate an Axios client from an OpenAPI document, similar to swagger-client. However, it leverages Axios for making HTTP requests, providing a more flexible and widely-used HTTP client.

swagger-js

swagger-js is another JavaScript client for Swagger/OpenAPI specifications. It provides similar functionality to swagger-client, allowing you to interact with APIs described by Swagger/OpenAPI documents. The main difference is in the implementation and API design, but both packages serve the same purpose.

README

Swagger Client

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.

Want to learn more? Check out our FAQ.

For features known to be missing from 3.x please see the Graveyard.

For the older version of swagger-js, refer to the 2.x branch.

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.

Compatibility

The OpenAPI Specification has undergone multiple revisions since initial creation in 2010. Compatibility between Swagger Client and the OpenAPI Specification is as follows:

Swagger Client Version	Release Date	OpenAPI Spec compatibility	Notes
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
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
3.10.x	2020-01-17	2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3	tag v3.10.0
2.1.32	2017-01-12	1.0, 1.1, 1.2	tag v2.1.32. This release is only available on GitHub.

Anonymized analytics

Swagger Client uses Scarf to collect anonymized installation analytics. These analytics help support the maintainers of this library and ONLY run during installation. To opt out, you can set the scarfSettings.enabled field to false in your project's package.json:

// package.json
{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

Alternatively, you can set the environment variable SCARF_ANALYTICS to false as part of the environment that installs your npm packages, e.g., SCARF_ANALYTICS=false npm install.

Documentation

Usage

• Installation
• Tags Interface
• HTTP client for OAS operations
• OpenAPI Definition Resolver
• HTTP Client
• Swagger Client API

Development

• Contributing
• Setting up
• Scripts

Migrations

• Migration guide
• Graveyard

Runtime

Node.js

swagger-client requires Node.js >=12.20.0 and uses different fetch implementation depending on Node.js version.

• >=12.20.0 <18 - node-fetch@3
• >=18 - native Node.js fetch

NOTE: swagger-client minimum Node.js runtime version aligns with Node.js Releases which means that we can drop support for EOL (End Of Life) Node.js versions without doing major version bump.

Browsers

swagger-client works in the latest versions of Chrome, Safari, Firefox, and Edge and uses native fetch implementation provided by each supported browser.

Security contact

Please disclose any security-related issues or vulnerabilities by emailing [e-mail], instead of using the public issue tracker.