route docs

lib/Tuba.pm

@@ -231,8 +231,10 @@ sub startup {
         $count = 1 unless $count =~ /^[0-9]+$/;
         return $c->render( text => "sorry, max is 1000 at once" ) if $count > 1000;
         $c->res->headers->content_type('text/plain');
-        $c->render(
-          text => join "\n", (map new_uuid_string(4), 1..$count)
+        $c->respond_to(
+          text => sub { shift->render( text => ( join "\n", (map new_uuid_string(4), 1..$count) ) ) },
+          html => sub { shift->render( text => ( join "\n", (map new_uuid_string(4), 1..$count) ) ) },
+          json => sub { shift->render( json => [ map new_uuid_string(4), 1..$count ] ) },
         );
       } => 'uuid'
     );

lib/Tuba/DocManager.pm

@@ -0,0 +1,41 @@
+=head1 NAME
+
+Tuba::DocManager -- manage documentation for routes.
+
+=cut
+
+package Tuba::DocManager;
+use Mojo::Base qw/-base/;
+use Tuba::RouteDoc;
+use Tuba::RouteParam;
+use Mojo::ByteStream qw/b/;
+
+our %RouteDoc = (
+  uuid => {
+    brief => "Generate a version 4 UUIDs",
+    description => b(q[<p>Generate version 4 Universally Unique Identifiers.  The algorithm used for this
+    is described <a target="_blank" href="https://en.wikipedia.org/wiki/UUID#Version_4_.28random.29">here</a>.
+    </p>]),
+    params      => [
+        {
+          name        => "count",
+          type        => "integer",
+          description => "Number of UUIDs to generate (max 1000)"
+        }
+    ]
+  },
+);
+
+sub find_doc {
+    my $c = shift;
+    my $route_name = shift;
+    my $entry = $RouteDoc{$route_name} or return;
+    return Tuba::RouteDoc->new(
+        name => $route_name,
+        brief => $entry->{brief},
+        description => $entry->{description},
+        params => [ map Tuba::RouteParam->new( %$_ ), @{ $entry->{params} } ]
+    );
+}
+
+1;

lib/Tuba/Plugin/TubaHelpers.pm

@@ -13,9 +13,11 @@ use Mojo::Base qw/Mojolicious::Plugin/;
 use Time::Duration qw/ago/;
 use List::Util qw/min/;
 use Date::Parse qw/str2time/;
+use DateTime::Format::Human::Duration;
+
 use Tuba::Util qw/get_config/;
 use Tuba::Log;
-use DateTime::Format::Human::Duration;
+use Tuba::DocManager;
 
 #
 # Usage :
@@ -364,6 +366,12 @@ sub register {
                 @{ $c->orm->{$table}->{mng}->get_objects(all => 1) };
             return wantarray ? @ids : \@ids;
     }); 
+    $app->helper(doc_for => sub {
+            my $c = shift;
+            my $route_name = shift;
+            state $mng //= Tuba::DocManager->new();
+            return $mng->find_doc($route_name);
+    });
 }
 
 1;

lib/Tuba/RouteDoc.pm

@@ -0,0 +1,15 @@
+=head1 NAME
+
+Tuba::RouteDoc -- documentation for a route.
+
+=cut
+
+package Tuba::RouteDoc;
+use Mojo::Base qw/-base/;
+
+has 'name';
+has 'description';
+has 'params';
+
+1;
+

lib/Tuba/RouteParam.pm

@@ -0,0 +1,15 @@
+=head1 NAME
+
+Tuba::RouteParam -- a single parameter for a route.
+
+=cut
+
+package Tuba::RouteParam;
+use Mojo::Base qw/-base/;
+
+has 'name';
+has 'type';
+has 'description';
+
+1;
+

lib/Tuba/files/templates/api_reference.html.ep

@@ -103,6 +103,16 @@ DELETE
   </div>
     % my $defaults = $trying->pattern->defaults;
     <div class='well'>
+        % my $doc = doc_for($trying->name);
+        %= $doc->description
+        % if (my $params = $doc->params) {
+        <div class='alert'>
+            Parameters :<br>
+            % for my $p (@$params) {
+                <%= $p->name %> (<%= $p->type %>) : <%= $p->description %><br>
+            % }
+        % }
+        </div>
         %= form_for 'try', method => 'POST', id => "theform", class => "form-horizontal" => begin
             %= hidden_field '_route_name' => $trying->name;
             % for my $p (@{ (stash 'placeholders') }) {