Hi,
I added a XML version of generated documentation. This will be used in command line client and can be used in 3th party applications as well.
- Michal
--- server/libexec/lib/sinatra/rabbit.rb | 3 +++ server/libexec/views/docs/collection.xml.haml | 18 ++++++++++++++++++ server/libexec/views/docs/index.xml.haml | 5 +++++ server/libexec/views/docs/operation.xml.haml | 13 +++++++++++++ 4 files changed, 39 insertions(+), 0 deletions(-) create mode 100644 server/libexec/views/docs/collection.xml.haml create mode 100644 server/libexec/views/docs/index.xml.haml create mode 100644 server/libexec/views/docs/operation.xml.haml
diff --git a/server/libexec/lib/sinatra/rabbit.rb b/server/libexec/lib/sinatra/rabbit.rb index 82a245b..4a51a4c 100644 --- a/server/libexec/lib/sinatra/rabbit.rb +++ b/server/libexec/lib/sinatra/rabbit.rb @@ -49,6 +49,7 @@ module Sinatra @collection, @operation = coll, oper respond_to do |format| format.html { haml :'docs/operation' } + format.xml { haml :'docs/operation' } end end end @@ -146,6 +147,7 @@ module Sinatra @collection, @operations = coll, oper respond_to do |format| format.html { haml :'docs/collection' } + format.xml { haml :'docs/collection' } end end end @@ -205,6 +207,7 @@ module Sinatra get '/api/docs/?' do respond_to do |format| format.html { haml :'docs/index' } + format.xml { haml :'docs/index' } end end
diff --git a/server/libexec/views/docs/collection.xml.haml b/server/libexec/views/docs/collection.xml.haml new file mode 100644 index 0000000..5cdac84 --- /dev/null +++ b/server/libexec/views/docs/collection.xml.haml @@ -0,0 +1,18 @@ +%docs + %collection{:url => "/api/docs/#{@collection.name}"} + %name #{@collection.name} + %description #{@collection.description} + %operations + - @operations.keys.sort_by { |k| k.to_s }.each do |operation| + %operation{:url => "/api/docs/#{@collection.name.to_s}/#{operation}"} + %name #{operation} + %description #{@operations[operation].description} + - @operations[operation].params.each_key do |p| + %parameter + %name #{p} + %type #{@operations[operation].params[p][:type]} + %class #{@operations[operation].params[p][:class]} + - unless @operations[operation].params[p][:options].empty? + %values + - @operations[operation].params[p][:options].each do |v| + %value #{v} diff --git a/server/libexec/views/docs/index.xml.haml b/server/libexec/views/docs/index.xml.haml new file mode 100644 index 0000000..bf64340 --- /dev/null +++ b/server/libexec/views/docs/index.xml.haml @@ -0,0 +1,5 @@ +%docs + - collections.keys.sort_by { |k| k.to_s }.each do |collection| + %collection{:url => "/api/docs/#{collection}"} + %name #{collection} + %description #{collections[collection].description} diff --git a/server/libexec/views/docs/operation.xml.haml b/server/libexec/views/docs/operation.xml.haml new file mode 100644 index 0000000..d935365 --- /dev/null +++ b/server/libexec/views/docs/operation.xml.haml @@ -0,0 +1,13 @@ +%docs + %operation{:url => "/api/docs/#{@collection.name.to_s}/#{@operation.name.to_s}"} + %name #{@operation.name.to_s} + %description #{@operation.description} + - @operation.params.each_key do |p| + %parameter + %name #{p} + %type #{@operation.params[p][:type]} + %class #{@operation.params[p][:class]} + - unless @operation.params[p][:options].empty? + %values + - @operation.params[p][:options].each do |v| + %value #{v}
On Wed, 2010-02-17 at 15:34 +0100, Michal Fojtik wrote:
I added a XML version of generated documentation. This will be used in command line client and can be used in 3th party applications as well.
Nice ... ACK, though I'd like to see a few changes in the XML output:
* Can you add something like 'status="unsupported"' to the toplevel <docs> element ? I don't want people to think this is part of the public API - I think we need to let this gel a little more before we can guarantee the stability of this format * For operations, I'd use a name attribute on the <operation> element to give the name, rather than a <name> child element. * It would be great to include information about how to perform each operation. Maybe as two additional attributes on each operation, href and method, so that you'd have
<operation url="..." href="/api/flavors/:id" method="get" name="show"/>
and
<operation url="..." href="/api/flavors" method="post" name="create"/> * Similarly, give the URL for the collection in an href attribute on the <collection/> tag * For parameters, make name and type attributes
BTW, your patch did not apply cleanly to the HEAD of master - it failed in rabbit.rb; I had to modify that file manually.
David
On 18/02/10 12:14 -0800, David Lutterkort wrote:
On Wed, 2010-02-17 at 15:34 +0100, Michal Fojtik wrote:
I added a XML version of generated documentation. This will be used in command line client and can be used in 3th party applications as well.
Nice ... ACK, though I'd like to see a few changes in the XML output:
* Can you add something like 'status="unsupported"' to the toplevel <docs> element ? I don't want people to think this is part of the public API - I think we need to let this gel a little more before we can guarantee the stability of this format * For operations, I'd use a name attribute on the <operation> element to give the name, rather than a <name> child element. * It would be great to include information about how to perform each operation. Maybe as two additional attributes on each operation, href and method, so that you'd have <operation url="..." href="/api/flavors/:id" method="get" name="show"/> and <operation url="..." href="/api/flavors" method="post" name="create"/> * Similarly, give the URL for the collection in an href attribute on the <collection/> tag * For parameters, make name and type attributes
Sure, I made this changes and they will be posted in this thread. This changes affecting 'deltacloud.rb' and views.
BTW, your patch did not apply cleanly to the HEAD of master - it failed in rabbit.rb; I had to modify that file manually
Weird, as far I remember I just pushed some 'format.xml { haml ... }' into rabbit.rb. Maybe I forgot some pull. I'll invetigate this later.
-- - Michal
--- server/libexec/views/docs/collection.xml.haml | 14 ++++++++++++++ server/libexec/views/docs/index.xml.haml | 5 +++++ server/libexec/views/docs/operation.xml.haml | 10 ++++++++++ 3 files changed, 29 insertions(+), 0 deletions(-) create mode 100644 server/libexec/views/docs/collection.xml.haml create mode 100644 server/libexec/views/docs/index.xml.haml create mode 100644 server/libexec/views/docs/operation.xml.haml
diff --git a/server/libexec/views/docs/collection.xml.haml b/server/libexec/views/docs/collection.xml.haml new file mode 100644 index 0000000..275bacc --- /dev/null +++ b/server/libexec/views/docs/collection.xml.haml @@ -0,0 +1,14 @@ +%docs{:status => "unsupported"} + %collection{:url => "/api/docs/#{@collection.name}", :name => "#{@collection.name}"} + %description #{@collection.description} + %operations + - @operations.keys.sort_by { |k| k.to_s }.each do |operation| + %operation{:url => "/api/docs/#{@collection.name.to_s}/#{operation}", :name => "#{operation}", :href => "/api/#{@collection.name.to_s}/#{operation}", :method => "#{@operations[operation].method}"} + %description #{@operations[operation].description} + - @operations[operation].params.each_key do |p| + %parameter{:name => "#{p}", :type => "#{@operations[operation].params[p][:type]}"} + %class #{@operations[operation].params[p][:class]} + - unless @operations[operation].params[p][:options].empty? + %values + - @operations[operation].params[p][:options].each do |v| + %value #{v} diff --git a/server/libexec/views/docs/index.xml.haml b/server/libexec/views/docs/index.xml.haml new file mode 100644 index 0000000..2210c8c --- /dev/null +++ b/server/libexec/views/docs/index.xml.haml @@ -0,0 +1,5 @@ +%docs{:status => "unsupported"} + - collections.keys.sort_by { |k| k.to_s }.each do |collection| + %collection{:url => "/api/docs/#{collection}"} + %name #{collection} + %description #{collections[collection].description} diff --git a/server/libexec/views/docs/operation.xml.haml b/server/libexec/views/docs/operation.xml.haml new file mode 100644 index 0000000..57f9775 --- /dev/null +++ b/server/libexec/views/docs/operation.xml.haml @@ -0,0 +1,10 @@ +%docs{:status => "unsupported"} + %operation{:url => "/api/docs/#{@collection.name.to_s}/#{@operation.name.to_s}", :name => "#{@operation.name.to_s}", :href => "/api/#{@collection.name.to_s}/#{@operation.name.to_s}", :method => "#{@operation.method}"} + %description #{@operation.description} + - @operation.params.each_key do |p| + %parameter{:name => "#{p}", :type => "#{@operation.params[p][:type]}"} + %class #{@operation.params[p][:class]} + - unless @operation.params[p][:options].empty? + %values + - @operation.params[p][:options].each do |v| + %value #{v}
--- client/lib/deltacloud.rb | 16 ++++++++-------- 1 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/client/lib/deltacloud.rb b/client/lib/deltacloud.rb index 2f9b59d..30056c1 100644 --- a/client/lib/deltacloud.rb +++ b/client/lib/deltacloud.rb @@ -122,29 +122,29 @@ class DeltaCloud response = @http["docs/#{collection}#{operation ? "/#{operation}" : ''}"].get(:accept => "application/xml") doc = REXML::Document.new( response ) if operation.nil? - docs = { - :name => doc.get_elements('docs/collection/name').first.text, - :description => doc.get_elements('docs/collection/description').first.text, - :operations => [] + docs = { + :name => doc.get_elements('docs/collection').first.attributes['name'], + :description => doc.get_elements('docs/collection/description').first.text, + :operations => [] } doc.get_elements('docs/collection/operations/operation').each do |operation| p = {} - p[:name] = operation.get_elements('name').first.text + p[:name] = operation.attributes['name'] p[:description] = operation.get_elements('description').first.text p[:parameters] = [] operation.get_elements('parameter').each do |param| - p[:parameters] << param.get_elements('name').first.text + p[:parameters] << param.attributes['name'] end docs[:operations] << p end else docs = { - :name => doc.get_elements('docs/operation/name').first.text, + :name => doc.get_elements('docs/operation').attributes['name'], :description => doc.get_elements('docs/operation/description').first.text, :parameters => [] } doc.get_elements('docs/operation/parameter').each do |param| - docs[:parameters] << param.get_elements('name').first.text + docs[:parameters] << param.attributes['name'] end end docs
deltacloud-devel@lists.fedorahosted.org