improved formatting of API docs; more API docs

3 files changed, 81 insertions, 30 deletions

diff --git a/web/lib/api/db.rb b/web/lib/api/db.rb
index d846a54..26478b1 100644
--- a/web/lib/api/db.rb
+++ b/web/lib/api/db.rb
@@ -2,18 +2,17 @@
 class Taginfo < Sinatra::Base
 
     @@filters = {
-        :characters_space       => { :expr => "characters='space'",   :doc => 'only show keys with spaces' },
-        :characters_problematic => { :expr => "characters='problem'", :doc => 'only show keys with problematic characters' },
-        :in_wiki                => { :expr => "in_wiki=1",            :doc => 'only show keys that appear in the wiki' },
-        :not_in_db              => { :expr => "count_all=0",          :doc => 'only show keys that do not appear in the database' }
+        :characters_space       => { :expr => "characters='space'",   :doc => 'Only show keys with spaces.' },
+        :characters_problematic => { :expr => "characters='problem'", :doc => 'Only show keys with problematic characters.' },
+        :in_wiki                => { :expr => "in_wiki=1",            :doc => 'Only show keys that appear in the wiki.' },
+        :not_in_db              => { :expr => "count_all=0",          :doc => 'Only show keys that do not appear in the database.' }
     }
 
     api(2, 'db/keys', {
         :description => 'Get list of keys that are in the database or mentioned in any other source.',
-        :parameters => nil,
+        :parameters => { :query => 'Only show keys matching this query (substring match, optional).' },
         :paging => :optional,
         :filter => @@filters,
-        :query => 'substring on key',
         :sort => %w( key count_all count_nodes count_ways count_relations values_all users_all in_wiki in_josm in_potlatch length ),
         :result => {
             :key                      => :STRING, 
@@ -139,7 +138,7 @@ class Taginfo < Sinatra::Base
 
     api(2, 'db/keys/overview', {
         :description => 'Show statistics for nodes, ways, relations and total for this key.',
-        :parameters => :key,
+        :parameters => { :key => 'Tag key (required).' },
         :paging => :no,
         :result => {
             :nodes => {
@@ -193,7 +192,7 @@ class Taginfo < Sinatra::Base
 
     api(2, 'db/keys/distribution', {
         :description => 'Get map with distribution of this key in the database.',
-        :parameters => [:key],
+        :parameters => { :key => 'Tag key (required).' },
         :result => 'PNG image.',
         :example => { :key => 'amenity' }
     }) do
@@ -205,17 +204,19 @@ class Taginfo < Sinatra::Base
     end
 
     api(2, 'db/keys/values', {
-        :description => 'Get values used with a given key',
-        :parameters => [:key],
+        :description => 'Get values used with a given key.',
+        :parameters => {
+            :key => 'Tag key (required).',
+            :query => 'Only show results where the value matches this query (substring match, optional).'
+        },
         :paging => :optional,
         :filter => {
-            :all       => { :doc => 'no filter' },
-            :nodes     => { :doc => 'only values on tags used on nodes' },
-            :ways      => { :doc => 'only values on tags used on ways' },
-            :relations => { :doc => 'only values on tags used on relations' }
+            :all       => { :doc => 'No filter.' },
+            :nodes     => { :doc => 'Only values on tags used on nodes.' },
+            :ways      => { :doc => 'Only values on tags used on ways.' },
+            :relations => { :doc => 'Only values on tags used on relations.' }
         },
         :sort => %w( value count_all count_nodes count_ways count_relations ),
-        :query => 'substring on value',
         :result => { :value => :STRING, :count => :INT, :fraction => :FLOAT },
         :example => { :key => 'highway', :page => 1, :rp => 10, :sortname => 'count_ways', :sortorder => 'desc' }
     }) do
@@ -266,13 +267,13 @@ class Taginfo < Sinatra::Base
 
     api(2, 'db/keys/keys', {
         :description => 'Find keys that are used together with a given key.',
-        :parameters => [:key],
+        :parameters => { :key => 'Tag key (required).' },
         :paging => :optional,
         :filter => {
-            :all       => { :doc => 'no filter' },
-            :nodes     => { :doc => 'only values on tags used on nodes' },
-            :ways      => { :doc => 'only values on tags used on ways' },
-            :relations => { :doc => 'only values on tags used on relations' }
+            :all       => { :doc => 'No filter.' },
+            :nodes     => { :doc => 'Only values on tags used on nodes.' },
+            :ways      => { :doc => 'Only values on tags used on ways.' },
+            :relations => { :doc => 'Only values on tags used on relations.' }
         },
         :sort => %w( together_count other_key from_fraction ),
         :result => {
@@ -361,7 +362,10 @@ class Taginfo < Sinatra::Base
 
     api(2, 'db/tags/overview', {
         :description => 'Show statistics for nodes, ways, relations and total for this tag.',
-        :parameters => [:key, :value],
+        :parameters => {
+            :key => 'Tag key (required).',
+            :value => 'Tag value (required).'
+        },
         :paging => :no,
         :result => {
             :nodes => {
diff --git a/web/lib/api/reports.rb b/web/lib/api/reports.rb
index 209e7cd..8045fee 100644
--- a/web/lib/api/reports.rb
+++ b/web/lib/api/reports.rb
@@ -2,7 +2,30 @@
 
 class Taginfo < Sinatra::Base
 
-    get '/api/2/reports/frequently_used_keys_without_wiki_page' do
+    api(2, 'reports/frequently_used_keys_without_wiki_page', {
+        :description => 'Return frequently used tag keys that have no associated wiki page.',
+        :parameters => {
+            :min_count => 'How many tags with this key must there be at least to show up here? (default 10000).',
+            :english => 'Check for key wiki pages in any language (0, default) or in the English language (1).',
+            :query => 'Only show results where the key matches this query (substring match, optional).'
+        },
+        :paging => :optional,
+        :sort => %w( key count_all values_all users_all ),
+        :result => {
+            :key                => :STRING,
+            :count_all          => :INT,
+            :count_all_fraction => :FLOAT,
+            :values_all         => :INT,
+            :users_all          => :INT,
+            :prevalent_values   => [{
+                :value    => :STRING,
+                :count    => :INT,
+                :fraction => :FLOAT
+            }]
+        },
+        :example => { :min_count => 1000, :english => '1', :page => 1, :rp => 10, :sortname => 'count_all', :sortorder => 'desc' },
+        :ui => '/reports/frequently_used_keys_without_wiki_page'
+    }) do
 
         min_count = params[:min_count].to_i || 10000
 
@@ -61,7 +84,22 @@ class Taginfo < Sinatra::Base
         }.to_json
     end
 
-    get '/api/2/reports/languages' do
+    api(2, 'reports/languages', {
+        :description => 'List languages Taginfo knows about and how many wiki pages describing keys and tags there are in these languages.',
+        :paging => :no,
+        :result => {
+            :code                    => :STRING,
+            :native_name             => :STRING,
+            :english_name            => :STRING,
+            :wiki_key_pages          => :INT,
+            :wiki_key_pages_fraction => :FLOAT,
+            :wiki_tag_pages          => :INT,
+            :wiki_tag_pages_fraction => :FLOAT
+        },
+        :sort => %w( code native_name english_name wiki_key_pages wiki_tag_pages ),
+        :example => { :sortname => 'wiki_key_pages', :sortorder => 'desc' },
+        :ui => '/reports/languages'
+    }) do
         res = @db.select('SELECT * FROM languages').
             order_by(params[:sortname], params[:sortorder]){ |o|
                 o.code
diff --git a/web/lib/apidoc.rb b/web/lib/apidoc.rb
index 26e4598..931bdb7 100644
--- a/web/lib/apidoc.rb
+++ b/web/lib/apidoc.rb
@@ -3,7 +3,7 @@ class APIDoc
 
     @@paths = {}
 
-    attr_accessor :version, :path, :parameters, :paging, :filter, :sort, :query, :result, :description, :example
+    attr_accessor :version, :path, :parameters, :paging, :filter, :sort, :result, :description, :example, :ui
 
     def self.paths
         @@paths
@@ -30,11 +30,20 @@ class APIDoc
         paging || 'no'
     end
 
+    def show_parameters
+        return '<i>none</i>' unless parameters
+        list = []
+        parameters.keys.sort{ |a,b| a.to_s <=> b.to_s }.each do |p|
+            list << "<tt>#{p}</tt> &mdash; #{parameters[p]}"
+        end
+        list.join('<br/>')
+    end
+
     def show_filter
         return '<i>none</i>' unless filter
         list = []
         filter.keys.sort{ |a,b| a.to_s <=> b.to_s }.each do |f|
-            list << "<tt>#{f}</tt> (#{filter[f][:doc]})"
+            list << "<tt>#{f}</tt> &mdash; #{filter[f][:doc]}"
         end
         list.join('<br/>')
     end
@@ -48,16 +57,16 @@ class APIDoc
         complete_path + '?' + params.join('&')
     end
 
+    def show_ui
+        return '' if example.nil?
+        ui
+    end
+
     def show_sort
         return '<i>none</i>' unless sort
         sort.map{ |s| "<tt>#{s}</tt>" }.join(', ')
     end
 
-    def show_query
-        return '<i>none</i>' unless query
-        query
-    end
-
     def show_result
         return '<i>unknown</i>' if result.nil?
         return result if result.is_a?(String)