This is the Wordnik Swagger javascript client for use with swagger enabled APIs.
It's written in CoffeeScript and tested with Jasmine.
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.
Usage
Point swagger.js at a resource discovery file like
api.wordnik.com/v4/resources.json
and it builds itself at runtime.
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script type="text/javascript" src="https://raw.github.com/wordnik/swagger.js/master/lib/swagger.js"></script>
<script type="text/javascript">
$(function() {
window.wordnik = new SwaggerApi({
discoveryUrl: "http://api.wordnik.com/v4/resources.json",
apiKey: "MY_API_KEY",
success: function() {
console.log('Shall we dance?');
}
});
});
</script>
How it Works
When initialized, the swagger.js client will build itself based on the (valid) swagger json files. You
initialize the client like such:
wordnik = new SwaggerApi({
discoveryUrl: "http://api.wordnik.com/v4/resources.json",
api_key: 'YOUR_API_KEY',
verbose: true,
success: function() { console.log("Your client is ready to swagger."); }
});
After executing the above code you should see the success message in your console.
Object Hierarchy
Now you have access to an object called wordnik
.
This object is what swagger.js builds at runtime when you
point it at a discoveryUrl
. Try exploring it in the console:
wordnik
wordnik.apis
wordnik.apis.word.operations
wordnik.apis.word.operations.getDefinition
Quick Reference
You also get some console help() methods for quick reference. Some examples:
wordnik.help()
wordnik.resource.word.help()
wordnik.apis.word.operations.getExamples.help()
Making Requests
There are two ways to make a request:
wordnik.word.getDefinitions(args, callback);
wordnik.apis.word.operations.getDefinitions.do(args, callback);
wordnik.word.getDefinitions({word: 'bliss'}, function(definitions) {
console.log(definitions);
})
You can include your own headers in the args object:
args = {word: 'swole', limit:5}
args.headers = {magic: 'potion'}
callback = function(examples) { console.log(examples); }
wordnik.word.getExamples(args, callback);
If you want to initialize the Request without actually firing
off a network request you can set a header called mock
with any value.
Request Body
For GETs and POSTs, you can include the request body in the args object:
args = {}
args.body = {name: "gizmo", description: "A thing that does stuff."}
callback = function(thing) { console.log(thing); }
myApi.things.createThing(args, callback);
Debugging / cURL
Set verbose
to true
when initializing your client to see cURL
equivalents of your requests in the browser console, complete with headers:
wordnik = new SwaggerApi({
api_key: 'YOUR_API_KEY',
verbose: true,
success: function() {
args = {
word: 'dog'
headers: {fubar: 'maybe'}
}
wordnik.word.getDefinitions.do(args, function(definitions){
console.log(definitions[0].word);
for (var i = 0; i < definitions.length; i++) {
var definition = definitions[i];
console.log(definition.partOfSpeech + ": " + definition.text);
}
});
}
});
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.
npm run-script build
npm run-script dev
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.