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

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

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org