Fixes & POD

- Changes attribute name in Raisin::Encoder;
- Fixes encoder.t;
- make_tag_from_path -2 or 1;
- export register_ functions;
- Updates examples;

Changes

@@ -1,5 +1,8 @@
 0.70 Formatters
-    * Removes x-www-form-urlencoded support
+    * Introduces a Formatters middleware and Encoder/Decoder modules;
+    * Removes Raisin::Response;
+    * Simplifies Raisin::Request;
+    * Drops x-www-form-urlencoded support;
 
 0.69 Documented responses
     * Fixes

README.md

@@ -4,14 +4,7 @@ Raisin - a REST API micro framework for Perl.
 
 # SYNOPSIS
 
-    use strict;
-    use warnings;
-
-    use utf8;
-
-    use FindBin;
-    use lib "$FindBin::Bin/../../lib";
-
+    use HTTP::Status qw(:constants);
     use List::Util qw(max);
     use Raisin::API;
     use Types::Standard qw(HashRef Any Int Str);
@@ -31,8 +24,12 @@ Raisin - a REST API micro framework for Perl.
         },
     );
 
-    plugin 'Swagger', enable => 'CORS';
-    #api_format 'json';
+    middleware 'CrossOrigin',
+        origins => '*',
+        methods => [qw/DELETE GET HEAD OPTIONS PATCH POST PUT/],
+        headers => [qw/accept authorization content-type api_key_token/];
+
+    plugin 'Swagger';
 
     swagger_setup(
         title => 'A POD synopsis API',
@@ -96,6 +93,7 @@ Raisin - a REST API micro framework for Perl.
             my $id = max(keys %USERS) + 1;
             $USERS{$id} = $params->{user};
 
+            res->status(HTTP_CREATED);
             { success => 1 }
         };
 
@@ -111,7 +109,9 @@ Raisin - a REST API micro framework for Perl.
             summary 'Delete user';
             del sub {
                 my $params = shift;
-                { success => delete $USERS{ $params->{id} } };
+                delete $USERS{ $params->{id} };
+                res->status(HTTP_NO_CONTENT);
+                undef;
             };
         };
     };
@@ -136,7 +136,8 @@ Adds a route to an application.
 
 ### route\_param
 
-Define a route parameter as a namespace `route_param`.
+Defines a route parameter as a resource `id` which can be anything if type
+isn't specified for it.
 
     route_param id => sub { ... };
 
@@ -165,8 +166,8 @@ Shortcuts to add a `route` restricted to the corresponding HTTP method.
 
 ### desc
 
-Can be applied to `resource` or any of the HTTP method to add a verbose
-explanation for an operation or for a resource.
+Adds a description to `resource` or any of the HTTP methods.
+Useful for OpenAPI as it's shown there as a description of an action.
 
     desc 'Some long explanation about an action';
     put sub { ... };
@@ -176,28 +177,25 @@ explanation for an operation or for a resource.
 
 ### summary
 
-Can be applied to any of the HTTP method to add a short summary of
-what the operation does.
+Same as ["desc"](#desc) but shorter.
 
     summary 'Some summary';
     put sub { ... };
 
 ### tags
 
-A list of tags for API documentation control.
 Tags can be used for logical grouping of operations by resources
-or any other qualifier.
+or any other qualifier. Using in API description.
 
     tags 'delete', 'user';
     delete sub { ... };
 
 By default tags are added automatically based on it's namespace but you always
-can overwrite it using a `tags` function.
+can overwrite it using the function.
 
 ### entity
 
-Entity keyword allows to describe response object which will be used to generate
-OpenAPI specification.
+Describes response object which will be used to generate OpenAPI description.
 
     entity 'MusicApp::Entity::Album';
     get {
@@ -208,7 +206,7 @@ OpenAPI specification.
 ### params
 
 Defines validations and coercion options for your parameters.
-Can be applied to any HTTP method and/or `route_param` to describe parameters.
+Can be applied to any HTTP method and/or ["route\_param"](#route_param) to describe parameters.
 
     params(
         requires('name', type => Str),
@@ -224,23 +222,25 @@ Can be applied to any HTTP method and/or `route_param` to describe parameters.
 
 For more see ["Validation-and-coercion" in Raisin](https://metacpan.org/pod/Raisin#Validation-and-coercion).
 
-### default\_format
+### api\_default\_format
 
-Specifies default API format mode when formatter doesn't specified by API user.
-E.g. URI is asked without an extension (`json`, `yaml`) or `Accept` header
-isn't specified.
+Specifies default API format mode when formatter isn't specified by API user.
+E.g. if URI is asked without an extension (`json`, `yaml`) or `Accept` header
+isn't specified the default format will be used.
 
 Default value: `YAML`.
 
-    default_format 'json';
+    api_default_format 'json';
 
 See also ["API-FORMATS" in Raisin](https://metacpan.org/pod/Raisin#API-FORMATS).
 
 ### api\_format
 
 Restricts API to use only specified formatter to serialize and deserialize data.
 
-Already exists [Raisin::Plugin::Format::JSON](https://metacpan.org/pod/Raisin::Plugin::Format::JSON) and [Raisin::Plugin::Format::YAML](https://metacpan.org/pod/Raisin::Plugin::Format::YAML).
+Already exists [Raisin::Encoder::JSON](https://metacpan.org/pod/Raisin::Encoder::JSON), [Raisin::Encoder::YAML](https://metacpan.org/pod/Raisin::Encoder::YAML),
+and [Raisin::Encoder::Text](https://metacpan.org/pod/Raisin::Encoder::Text), but you can always register your own
+using ["register\_encoder"](#register_encoder).
 
     api_format 'json';
 
@@ -257,7 +257,7 @@ Sets up an API version header.
 Loads a Raisin module. A module options may be specified after the module name.
 Compatible with [Kelp](https://metacpan.org/pod/Kelp) modules.
 
-    plugin 'Swagger', enable => 'CORS';
+    plugin 'Swagger';
 
 ### middleware
 
@@ -285,6 +285,22 @@ In `RaisinApp.pm`:
 
     1;
 
+### register\_decoder
+
+Registers a third-party parser (decoder).
+
+    register_decoder(xml => 'My::Parser::XML');
+
+Also see [Raisin::Decoder](https://metacpan.org/pod/Raisin::Decoder).
+
+### register\_encoder
+
+Registers a third-party formatter (encoder).
+
+    register_encoder(xml => 'My::Formatter::XML');
+
+Also see [Raisin::Encoder](https://metacpan.org/pod/Raisin::Encoder).
+
 ### run
 
 Returns the `PSGI` application.
@@ -421,11 +437,11 @@ Multipart `POST`s and `PUT`s are supported as well.
 
 In the case of conflict between either of:
 
-- route string parameters;
+- path parameters;
 - GET, POST and PUT parameters;
 - contents of request body on POST and PUT;
 
-route string parameters will have precedence.
+Path parameters have precedence.
 
 Query string and body parameters will be merged (see ["parameters" in Plack::Request](https://metacpan.org/pod/Plack::Request#parameters))
 
@@ -600,7 +616,7 @@ Serialization takes place automatically. So, you do not have to call
 Your API can declare to support only one serializator by using ["api\_format" in Raisin](https://metacpan.org/pod/Raisin#api_format).
 
 Custom formatters for existing and additional types can be defined with a
-[Raisin::Plugin::Format](https://metacpan.org/pod/Raisin::Plugin::Format).
+[Raisin::Encoder](https://metacpan.org/pod/Raisin::Encoder)/[Raisin::Decoder](https://metacpan.org/pod/Raisin::Decoder).
 
 - JSON
 
@@ -610,7 +626,7 @@ Custom formatters for existing and additional types can be defined with a
 
     Call `YAML::Dump` and `YAML::Load`.
 
-- TEXT
+- Text
 
     Call `Data::Dumper->Dump` if output data is not a string.
 

examples/music-app/script/music_app_dbix.psgi

@@ -4,7 +4,7 @@ use strict;
 use warnings;
 
 use FindBin '$Bin';
-use lib ("$Bin/../../../lib", "$Bin/../lib");
+use lib "$Bin/../lib";
 
 use Raisin::API;
 use Raisin::Entity;
@@ -18,7 +18,12 @@ use MusicApp::Schema;
 
 my $schema = MusicApp::Schema->connect("dbi:SQLite:$Bin/../db/music.db");
 
-plugin 'Swagger', enable => 'CORS';
+plugin 'Swagger';
+middleware 'CrossOrigin',
+    origins => '*',
+    methods => [qw/DELETE GET HEAD OPTIONS PATCH POST PUT/],
+    headers => [qw/accept authorization content-type api_key_token/];
+
 api_default_format 'yaml';
 
 desc 'Artist API';

examples/music-app/script/music_app_rdbo.psgi

@@ -4,7 +4,7 @@ use strict;
 use warnings;
 
 use FindBin '$Bin';
-use lib ("$Bin/../../../lib", "$Bin/../lib");
+use lib "$Bin/../lib";
 
 use Raisin::API;
 use Raisin::Entity;
@@ -17,7 +17,12 @@ use MusicApp::Entity::Album;
 use MusicApp::RDBO::Artist;
 use MusicApp::RDBO::Album;
 
-plugin 'Swagger', enable => 'CORS';
+plugin 'Swagger';
+middleware 'CrossOrigin',
+    origins => '*',
+    methods => [qw/DELETE GET HEAD OPTIONS PATCH POST PUT/],
+    headers => [qw/accept authorization content-type api_key_token/];
+
 api_default_format 'yaml';
 
 desc 'Artist API';

examples/pod-synopsis-app/darth.pl

@@ -3,11 +3,7 @@
 use strict;
 use warnings;
 
-use utf8;
-
-use FindBin;
-use lib "$FindBin::Bin/../../lib";
-
+use HTTP::Status qw(:constants);
 use List::Util qw(max);
 use Raisin::API;
 use Types::Standard qw(HashRef Any Int Str);
@@ -27,8 +23,12 @@
     },
 );
 
-plugin 'Swagger', enable => 'CORS';
-#api_format 'json';
+middleware 'CrossOrigin',
+    origins => '*',
+    methods => [qw/DELETE GET HEAD OPTIONS PATCH POST PUT/],
+    headers => [qw/accept authorization content-type api_key_token/];
+
+plugin 'Swagger';
 
 swagger_setup(
     title => 'A POD synopsis API',
@@ -96,6 +96,7 @@
         my $id = max(keys %USERS) + 1;
         $USERS{$id} = $params->{user};
 
+        res->status(HTTP_CREATED);
         { success => 1 }
     };
 
@@ -111,7 +112,9 @@
         summary 'Delete user';
         del sub {
             my $params = shift;
-            { success => delete $USERS{ $params->{id} } };
+            delete $USERS{ $params->{id} };
+            res->status(HTTP_NO_CONTENT);
+            undef;
         };
     };
 };

examples/sample-app/lib/RESTApp.pm

@@ -10,7 +10,12 @@ use lib ("$Bin/../lib", "$Bin/../../../lib");
 
 use Raisin::API;
 
-plugin 'Swagger', enable => 'CORS';
+plugin 'Swagger';
+middleware 'CrossOrigin',
+    origins => '*',
+    methods => [qw/DELETE GET HEAD OPTIONS PATCH POST PUT/],
+    headers => [qw/accept authorization content-type api_key_token/];
+
 plugin 'Logger', outputs => [['Screen', min_level => 'debug']];
 
 swagger_setup(

examples/sample-app/script/restapp.psgi

@@ -6,8 +6,7 @@ use warnings;
 use FindBin '$Bin';
 use Plack::Builder;
 
-# Include lib and Raisin/lib
-use lib ("$Bin/../lib", "$Bin/../../../lib");
+use lib "$Bin/../lib";
 
 use RESTApp;