Git Product home page Git Product logo

swagger-js's Introduction

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

Find out more about the swagger project at swagger.wordnik.com, and follow us on Twitter at @swagger_doc.

READ MORE about swagger!

See the swagger website or the swagger-core wiki, which contains information about the swagger json spec.

Calling an API with swagger + node.js!

Install swagger-client:

npm install swagger-client

Then let swagger do the work!

var swagger = require("swagger-client")

var s = new swagger.SwaggerApi({
  url: 'http://localhost:8002/api/api-docs'
});
s.build();

s.apis.pet.getPetById({petId:1});

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:

swagger.authorizations.add("apiKey", new swagger.ApiKeyAuthorization("api_key","special-key","query"));

...or with a header:

swagger.authorizations.add("apiKey", new swagger.ApiKeyAuthorization("api_key","special-key","header"));

Calling an API with swagger + the browser!

Download swagger.js and shred.bundle.js into your lib folder

<script src='lib/shred.bundle.js' type='text/javascript'></script>
<script src='lib/swagger.js' type='text/javascript'></script>
<script type="text/javascript">
  // initialize swagger, point to a resource listing
  window.swagger = new SwaggerApi({url: "http://petstore.swagger.wordnik.com/api/api-docs.json"});
  swagger.build();

  // add a success handler to dump the raw json into a div element named `mydata`
  success = function(data) {
    document.getElementById("mydata").innerHTML = data.content.data;
  }

  // a function to fetch a pet
  function getPet() {
    swagger.apis.pet.getPetById({petId:1}, success);
  }
</script>

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

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

swagger.apis.pet.addPet({body: JSON.stringify(body)});

Sending XML in as a payload to your API?

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

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

Need XML response?

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

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.js. Send us a pull request and we'll mail you a wordnik T-shirt!

Swagger.js is written in CoffeeScript, so you'll need Node.js and the CoffeeScript compiler. For more detailed installation instructions, see coffeescript.org/#installation.

# generate the javascript libraries and put them in the `lib` folder

npm run-script build
# The 'dev' task will:
# 1. Open source files in your $EDITOR
# 2. Open and run the Jasmine specs in your browser.
# 3. Watch for changes to CoffeeScript files and auto-compile them to Javascript.

npm run-script dev

# List all cake tasks:
cake

License

Copyright 2011-2013 Wordnik, Inc.

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.

swagger-js's People

Contributors

ayush avatar danieleli avatar dilipkrish avatar fehguy avatar filirom1 avatar kara-ryli avatar leedm777 avatar pdegeus avatar pose avatar rintcius avatar sr3d avatar zeke avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.