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 JS library

This is the Swagger javascript client for use with swagger enabled APIs. It's written in javascript and tested with mocha, and is the fastest way to enable a javascript client to communicate with a swagger-enabled server.

Check out Swagger-Spec for additional information about the Swagger project, including additional libraries with support for other languages and more.

Calling an API with swagger + node.js!

Install swagger-client:

npm install swagger-client

or:

bower install swagger-js

Then let swagger do the work!

var client = require('swagger-client');

var swagger = new client({
  url: 'http://petstore.swagger.io/v2/swagger.json',
  success: function() {
    swagger.pet.getPetById({petId:7},{responseContentType: 'application/json'},function(pet){
      console.log('pet', pet);
    });
  }
});

NOTE: we're explicitly setting the responseContentType, because we don't want you getting stuck when there is more than one content type available.

That's it! You'll get a JSON response with the default callback handler:

{
  "id": 1,
  "category": {
    "id": 2,
    "name": "Cats"
  },
  "name": "Cat 1",
  "photoUrls": [
    "url1",
    "url2"
  ],
  "tags": [
    {
      "id": 1,
      "name": "tag1"
    },
    {
      "id": 2,
      "name": "tag2"
    }
  ],
  "status": "available"
}

Need to pass an API key? Configure one as a querystring:

client.clientAuthorizations.add("apiKey", new client.ApiKeyAuthorization("api_key","special-key","query"));

...or with a header:

client.clientAuthorizations.add("apiKey", new client.ApiKeyAuthorization("api_key","special-key","header"));

...or with the swagger-client constructor:

var swagger = new client({
  url: 'http://example.com/spec.json',
  success: function() {},
  authorizations : {
    easyapi_basic: new client.PasswordAuthorization('<username>', '<password>'),
    someHeaderAuth: new client.ApiKeyAuthorization('<nameOfHeader>', '<value>', 'header'),
    someQueryAuth: new client.ApiKeyAuthorization('<nameOfQueryKey>', '<value>', 'query'),
    someCookieAuth: new client.CookieAuthorization('<cookie>'),
  }
});

Calling an API with swagger + the browser!

Download browser/swagger-client.js into your webapp:

<script src='browser/swagger-client.js' type='text/javascript'></script>
<script type="text/javascript">
  // initialize swagger, point to a resource listing
  window.swagger = new SwaggerClient({
    url: "http://petstore.swagger.io/api/api-docs",
    success: function() {
      // upon connect, fetch a pet and set contents to element "mydata"
      swagger.apis.pet.getPetById({petId:1},{responseContentType: 'application/json'}, function(data) {
        document.getElementById("mydata").innerHTML = JSON.stringify(data.obj);
      });
    }
  });
</script>

<body>
  <div id="mydata"></div>
</body>

Need to send an object to your API via POST or PUT?

var pet = {
  id: 100,
  name: "dog"};

swagger.pet.addPet({body: pet});

Sending XML in as a payload to your API?

var pet = "<Pet><id>2</id><name>monster</name></Pet>";

swagger.pet.addPet({body: pet}, {requestContentType:"application/xml"});

Need XML response?

swagger.pet.getPetById({petId:1}, {responseContentType:"application/xml"});

Custom request signing

You can easily write your own request signing code for Swagger. For example:

var CustomRequestSigner = function(name) {
  this.name = name;
};

CustomRequestSigner.prototype.apply = function(obj, authorizations) {
  var hashFunction = this._btoa;
  var hash = hashFunction(obj.url);

  obj.headers["signature"] = hash;
  return true;
};

In the above simple example, we're creating a new request signer that simply base 64 encodes the URL. Of course you'd do something more sophisticated, but after encoding it, a header called signature is set before sending the request.

How does it work?

The swagger javascript client reads the swagger api definition directly from the server. As it does, it constructs a client based on the api definition, which means it is completely dynamic. It even reads the api text descriptions (which are intended for humans!) and provides help if you need it:

s.apis.pet.getPetById.help()
'* petId (required) - ID of pet that needs to be fetched'

The HTTP requests themselves are handled by the excellent shred library, which has a ton of features itself. But it runs on both node and the browser.

Development

Please fork the code and help us improve swagger-client.js. Send us a pull request to the master branch! Tests make merges get accepted more quickly.

swagger-js use gulp for Node.js.

# Install the gulp client on the path
npm install -g gulp

# Install all project dependencies
npm install

# List all tasks.
gulp -T

# Run lint (will not fail if there are errors/warnings), tests (without coverage) and builds the browser binaries
gulp

# Run the test suite (without coverage)
gulp test

# Build the browser binaries (One for development with source maps and one that is minified and without source maps) in the browser directory
gulp build

# Continuously run the test suite:
gulp watch

# Run jshint report
gulp lint

# Run a coverage report based on running the unit tests
gulp coverage

License

Copyright 2011-2015 SmartBear Software

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.