NAME

       Swagger2::Guides::Tutorial - Tutorial for Mojolicious::Plugin::Swagger2

OVERVIEW

       This tutorial will give you an introduction to how to use Mojolicious::Plugin::Swagger2.

       You can also check out <https://github.com/jhthorsen/swagger2/tree/master/t/blog> if you
       want to look at a complete example application.

       Another resources is the blog post
       <http://thorsen.pm/perl/programming/2015/07/05/mojolicious-swagger2.html>, which includes
       reasons for why you want to use Swagger2.

TUTORIAL

   Swagger specification
       The input "url" to given as argument to the plugin need to point to a valid swagger
       <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md> document.

       Every operation must have "operationId" specified, so this plugin knows where to look for
       the controller and method. The naming convention is:

         "operationId": "methodControllerOptions"

       Example specification:

         {
           "swagger": "2.0",
           "basePath": "/api",
           "paths": {
             "/pets/{petId}": {
               "get": {
                 "operationId": "showPetById",
                 "parameters": [ ... ],
                 "responses": {
                   "200": { ... }
                 }
               }
             }
           }
         }

       Here the "operationId" contains the method "show" and the controller "Pet".  The "Pet"
       controller will again expand to "MyApp::Controller::Pet" or "MyApp::Pet" or whatever
       "namespaces" in Mojolicious::Routes is set to. The "options" part (ById) is simply
       ignored.

       Note that "showPetById" and "listPets" will both result in looking for the "Pet"
       controller, since the plural ending ("s") is removed.

       The table below try to illustrate how the controller/method is resolved:

         .---------------------------------------------------------------.
         | operationId            | Controller   | Method      | Ignored |
         |------------------------|--------------|-------------|---------|
         | childrenOfPerson       | Person       | children    | Of      |
         | designByUser           | User         | design      | By      |
         | fooWithBar             | Bar          | foo         | With    |
         | getPetById             | Pet          | get         | ById    |
         | listUsers              | User         | list        | s       |
         | peopleInConversation   | Conversation | people      | In      |
         | searchForPets          | Pet          | search      | For, s  |
         | sendToConversation     | Conversation | send        | To      |
         | createFileInFileSystem | FileSystem   | create_file | In      |
         | removeFromFileSystem   | FileSystem   | remove      | From    |
         '---------------------------------------------------------------'

       The operationId rules will be updated if bugs or incompatibility is discovered.

   Application
       The application need to load the Mojolicious::Plugin::Swagger2 plugin, with a URL to the
       API specification. The plugin will then add all the routes defined in the "Swagger
       specification".

         package MyApp;
         use Mojo::Base "Mojolicious";

         sub startup {
           my $app = shift;
           $app->plugin(Swagger2 => { url => app->home->rel_file("api.json") });
         }

   Controller
       The method names defined in the controller will be a decamelized version of "operationId".

       The example "Swagger specification" above, will result in "show()" in the controller below
       to be called. This method will receive the current Mojolicious::Controller object, input
       arguments and a callback. The callback should be called with a HTTP status code, and a
       data structure which will be validated and serialized back to the user agent.

       $args (input arguments) will be a hash, where the keys match "name" in the "parameters"
       defined in the Swagger spec, and the values are whatever input came from the client. This
       also goes for the "body" parameter: This means that the input JSON from HTTP body will not
       be flattened, but stored under the body parameter name in $args.

         package MyApp::Controller::Pet;

         sub show {
           my ($c, $args, $cb) = @_;

           # Example $args:
           # $args->{body_param_name}  == $c->req->json
           # $args->{query_param_name} == $c->req->url->query->param("query_param_name")
           # $args->{"X-Header-Name"}  == $c->req->headers->header("X-Header-Name")

           $c->$cb({limit => 123}, 200);
         }

SEE ALSO

       •   Swagger2::Guides::ProtectedApi - Protected API Guide

AUTHOR

       Jan Henning Thorsen - "jhthorsen@cpan.org"