DSL to describe, document and test web services
DSL to describe, document and test web services
Weasel Diesel is a DSL to describe and document your web API.
To get you going quickly, see the generator for sinatra apps. The wd_sinatra gem allows you to generate the structure for a sinatra app using Weasel Diesel and with lots of goodies. Updating is trivial since the core features are provided by this library and the wd_sinatra gem.
You can also check out this Sinatra-based example application that you can fork and use as a base for your application.
DSL examples:
…Or a more complex example using XML:
…ruby service.params do |param| param.string :framework, :in => ['RSpec', 'Bacon'], :required => true, :doc => "The test framework used, could be one of the two following: #{WeaselDieselSpecOptions.join(", ")}."
param.datetime :timestamp, :default => Time.now
param.string :alpha, :in => ['a', 'b', 'c']
param.string :version, :null => false, :doc => "The version of the framework to use."
param.integer :num, :min_value => 42, :max_value => 1000, :doc => "The number to test"
param.string :name, :min_length => 5, :max_length => 25
end
service.params.namespace :user do |user| user.integer :id, :required => :true user.string :sex, :in => %Q{female, male} user.boolean :mailing_list, :default => true, :doc => "is the user subscribed to the ML?" user.array :skills, :in => %w{ruby js cooking} end
service.params.namespace :attachment, :null => true do |attachment| attachment.string :url, :required => true end
Here is the same type of input but this time using a JSON jargon,
`namespace` and `object` are aliases and can therefore can be used based
on how the input type.
```ruby
# INPUT using 1.9 hash syntax
service.params do |param|
param.integer :playlist_id,
doc: "The ID of the playlist to which the track belongs.",
required: true
param.object :track do |track|
track.string :title,
doc: "The title of the track.",
required: true
track.string :album_title,
doc: "The title of the album to which the track belongs.",
required: true
track.string :artist_name,
doc: "The name of the track's artist.",
required: true
track.string :rdio_id,
doc: "The Rdio ID of the track.",
required: true
end
endConsider the following JSON response:
{ people: [
{
id : 1,
online : false,
created_at : 123123123123,
team : {
id : 1231,
score : 123.32
}
},
{
id : 2,
online : true,
created_at : 123123123123,
team: {
id : 1233,
score : 1.32
}
},
] }It would be described as follows:
describe_service "/json_list" do |service|
service.formats :json
service.response do |response|
response.array :people do |node|
node.integer :id
node.boolean :online
node.datetime :created_at
node.object :team do |team|
team.integer :id
team.float :score, :null => true
end
end
end
endNodes/elements can also use some meta-attributes including:
key : refers to an attribute name that is key to this objecttype : refers to the type of object described, valuable when using JSON across OO based apps.JSON response validation can be done using an optional module as shown in (spec/json_response_verification_spec.rb)[https://github.com/mattetti/Weasel-Diesel/blob/master/spec/json_response_verification_spec.rb]. The goal of this module is to help automate API testing by validating the data structure of the returned object.
Another simple examples:
Actual output:
{"organization": {"name": "Example"}}Output DSL:
describe_service "example" do |service|
service.formats :json
service.response do |response|
response.object :organization do |node|
node.string :name
end
end
endActual output:
{"name": "Example"}Output DSL:
describe_service "example" do |service|
service.formats :json
service.response do |response|
response.object do |node|
node.string :name
end
end
end $ weasel_diesel generate_doc To generate documentation for the APIs you created in the api folder. The source path is the location of your ruby files. The destination is optional, 'doc' is the default.
Here's a sample of what the generator documentation looks like.
The test suite requires rspec, rack, and sinatra gems.
Copyright (c) 2012 Matt Aimonetti. See LICENSE for further details.
No open issues yet, or sync has not completed.