You have to call OpenAPIRoutes([$debug_flag, $custom_map]) in your main application module. Optionally you can pass true value as first argument to see how it maps routes to Modules and functions.

SMART MAPPING

This is probably the most crucial feature of this plugin. It automatically makes your application structured according to given spec file. It also makes your application less dependent on Dancer2 framework - you have to think more about application logic and less about framework details. Mapping is complicated but intuitive.

MAPPING RULES

Both the route and its HTTP method are used to compose the mapping.

HTTP METHOD MAPPING

This is starting point of the mapping algorithm. If route has only one method, then route's last part can be used as function name in module which name made of previous route parts.

POST

In RESful terms POST means creation of some resource. That's why usually it maps to create() function with one exception: if route ends with /{someId} then it means update().

GET

This methis is mapped to function fetch().

DELETE

This method is mapped to remove(). Perl language already has delete() function and it's better not to reuse its name.

PUT

In RESful terms PUT means full replacement of some resource. This method is mapped to replace()

PATCH

In RESful terms PATCH means partial update of some resource. This method is mapped to update()

OPTIONS

This method is mapped to choices()

HEAD

This method is mapped to check()

You don't usually have to define HEAD method because it's done automatically from GET throwing away real answer.

ROUTES MAPPING

Basic idea is very simple: /resource/subresource is mapped to Resource::Subresource module and function name is mapped according HTTP method. Then there're special cases (from OpenAPI example spec):

POST/pet/{petId}/uploadImage

GET/pet/findByTags

GET/pet/findByStatus

It would be silly to put these three routes with single method in separate modules Pet::UploadImage, Pet::FindByTags and Pet::FindByStatus. That's why routes with only one method are mapped to theirs "parents" with function name from last route part.

NOTICE: It's important to describe path parameters twice: in route and in parameters method's section. Because they are extracted as regexp captures and routes with integer parameters should be dispatched first to avoid collision between /pet/{petId} and /pet/findByTags type of routes.

INTERFACE

ENVIRONMENT VARIABLES

When you need some variable from PSGI's environment, like REMOTE_USER, then it's really inconvenient to get directly from Dancer2 framework. There's a support to get it automatic using OpenAPI extension keyword x-env-{environment-variable} like x-env-remote-user: user. This keyword should be put in HTTP method section. Directive x-env-remote-user: user will put value of PSGI's environment variable REMOTE_USER into input hash parameter key user.

FUNCTION INTERFACE

Function receives hash reference with extracted parameters according to Swagger spec and Dancer2DSL object. This object is rarely needed but sometimes you need to have access to application's object, for example:

CUSTOM MAPPING

When you need some customization to your routes mapping, you can do it passing hash reference as second parameter to OpenAPIRoutes([$debug, $castom_map]). You can change mapping for HTTP method for all paths or only for specific ones like this:

OpenAPIRoutes(1, {"get:/store/order/{orderId}" => "remove"});

(Very naughty joke): Instead of calling "fetch" for this specific path it will call "remove". The whole schema: