---
name: "Mojolicious::Plugin::Swagger2"
section: "3pm"
platform: "linux"
package: "libswagger2-perl"
version: "0.77-1"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/Mojolicious::Plugin::Swagger2"
---

# Mojolicious::Plugin::Swagger2(3pm)

Mojolicious plugin for Swagger2

## NAME

Mojolicious::Plugin::Swagger2 - Mojolicious plugin for Swagger2

## SYNOPSIS

```
  package MyApp;
  use Mojo::Base "Mojolicious";
  sub startup {
    my $app = shift;
    $app->plugin(Swagger2 => {url => "data://MyApp/petstore.json"});
  }
  __DATA__
  @@ petstore.json
  {
    "swagger": "2.0",
    "info": {...},
    "host": "petstore.swagger.wordnik.com",
    "basePath": "/api",
    "paths": {
      "/pets": {
        "get": {...}
      }
    }
  }
```

## DESCRIPTION

Mojolicious::Plugin::Swagger2 is Mojolicious::Plugin that add routes and input/output validation to your Mojolicious application.

Have a look at the "RESOURCES" for a complete reference to what is possible or look at Swagger2::Guides::Tutorial for an introduction.

## RESOURCES

- •

  Swagger2::Guides::Tutorial - Tutorial for this plugin

- •

  Swagger2::Guides::Render - Details about the render process

- •

  Swagger2::Guides::ProtectedApi - Protected API Guide

- •

  Swagger2::Guides::CustomPlaceholder - Custom placeholder for your routes

- •

  Swagger2::Guides::JSONSchemaSupport - Adding json-schema support - EXPERIMENTAL

- •

  Swagger spec \<https://github.com/jhthorsen/swagger2/blob/master/t/blog/api.json\>

- •

  Application \<https://github.com/jhthorsen/swagger2/blob/master/t/blog/lib/Blog.pm\>

- •

  Controller \<https://github.com/jhthorsen/swagger2/blob/master/t/blog/lib/Blog/Controller/Posts.pm\>

- •

  Tests \<https://github.com/jhthorsen/swagger2/blob/master/t/authenticate.t\>

## HOOKS

### swagger\_route\_added

This hook will be DEPRECATED! See \<https://github.com/jhthorsen/swagger2/issues/65\>.

## STASH VARIABLES

### swagger

The Swagger2 object used to generate the routes is available as `"swagger"` from stash. Example code:

```
  sub documentation {
    my ($c, $args, $cb);
    $c->$cb($c->stash('swagger')->pod->to_string, 200);
  }
```

### swagger\_operation\_spec

The Swagger specification for the current operation object \<https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject\> is stored in the "swagger\_operation\_spec" stash variable.

```
  sub list_pets {
    my ($c, $args, $cb);
    $c->app->log->info($c->stash("swagger_operation_spec")->{operationId});
    ...
  }
```

## ATTRIBUTES

### url

Holds the URL to the swagger specification file.

## HELPERS

### dispatch\_to\_swagger

```
  $bool = $c->dispatch_to_swagger(\%data);
```

This helper can be used to handle WebSocket requests with swagger. See Swagger2::Guides::WebSocket for details.

This helper is EXPERIMENTAL.

### render\_swagger

```
  $c->render_swagger(\%err, \%data, $status);
```

This method is used to render `%data` from the controller method. The `%err` hash will be empty on success, but can contain input/output validation errors. `$status` is used to set a proper HTTP status code such as 200, 400 or 500.

See also Swagger2::Guides::Render for more information.

## METHODS

### register

```
  $self->register($app, \%config);
```

This method is called when this plugin is registered in the Mojolicious application.

`%config` can contain these parameters:

- •

  coerce

  This argument will be passed on to "coerce" in JSON::Validator.

- •

  ensure\_swagger\_response

  ```
    $app->plugin(swagger2 => {
      ensure_swagger_response => {
        exception => "Internal server error.",
        not_found => "Not found.",
      }
    });
  ```

  Adds a before\_render hook which will make sure "exception" and "not\_found" responses are in JSON format. There is no need to specify "exception" and "not\_found" if you are happy with the defaults.

- •

  route

  Need to hold a Mojolicious route object. See "Protected API" for an example.

  This parameter is optional.

- •

  spec\_path

  Holds the location for where the specifiation can be served from. The default value is "/", relative to "basePath" in the specification. Can be disabled by setting this value to empty string.

- •

  validate

  A boolean value (default is true) that will cause your schema to be validated. This plugin will abort loading if the schema include errors

- •

  swagger

  A `"Swagger2"` object. This can be useful if you want to keep use the specification to other things in your application. Example:

  ```
    use Swagger2;
    my $swagger = Swagger2->new->load($url);
    plugin Swagger2 => {swagger => $swagger2};
    app->defaults(swagger_spec => $swagger->api_spec);
  ```

  Either this parameter or `"url"` need to be present.

- •

  url

  This will be used to construct a new Swagger2 object. The `"url"` can be anything that "load" in Swagger2 can handle.

  Either this parameter or `"swagger"` need to be present.

## COPYRIGHT AND LICENSE

Copyright (C) 2014-2015, Jan Henning Thorsen

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

## AUTHOR

Jan Henning Thorsen - `"jhthorsen@cpan.org"`