/ 
Swagger2-0.55
River stage zero No dependents
/ Swagger2::Guides::Tutorial

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 document.

Every operation must have a "x-mojo-controller" specified, so this plugin knows where to look for the decamelized "operationId", which is used as method name. x-mojo-controller can be defined on different levels and gets inherited unless defined more specific:

{
  "swagger": "2.0",
  "basePath": "/api",
  "x-mojo-controller": "MyApp::Controller::Default",
  "paths": {
    "/pets": {
      "x-mojo-controller": "MyApp::Controller::ForEveryHttpMethodUnderPets",
      "get": {
        "x-mojo-controller": "MyApp::Controller::Petstore",
        "x-mojo-around-action": "MyApp::authenticate_api_request",
        "operationId": "listPets",
        "parameters": [ ... ],
        "responses": {
          "200": { ... }
        }
      }
    }
  }
}

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.yaml") });
}

Controller

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

The example "Swagger specification" above, will result in list_pets() 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.

package MyApp::Controller::Petstore;

sub list_pets {
  my ($c, $input, $cb) = @_;
  $c->$cb({limit => 123}, 200);
}

SEE ALSO

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org