--- name: "Mojolicious::Plugin::OpenAPI" section: "3pm" platform: "linux" package: "libmojolicious-plugin-openapi-perl" version: "5.11-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Mojolicious::Plugin::OpenAPI" --- # Mojolicious::Plugin::OpenAPI(3pm) OpenAPI / Swagger plugin for Mojolicious ## NAME Mojolicious::Plugin::OpenAPI - OpenAPI / Swagger plugin for Mojolicious ## SYNOPSIS ``` # It is recommended to use Mojolicious::Plugin::OpenAPI with a "full app". # See the links after this example for more information. use Mojolicious::Lite; # Because the route name "echo" matches the "x-mojo-name", this route # will be moved under "basePath", resulting in "POST /api/echo" post "/echo" => sub { # Validate input request or return an error document my $c = shift->openapi->valid_input or return; # Generate some data my $data = {body => $c->req->json}; # Validate the output response and render it to the user agent # using a custom "openapi" handler. $c->render(openapi => $data); }, "echo"; # Load specification and start web server plugin OpenAPI => {url => "data:///swagger.yaml"}; app->start; __DATA__ @@ swagger.yaml swagger: "2.0" info: { version: "0.8", title: "Echo Service" } schemes: ["https"] basePath: "/api" paths: /echo: post: x-mojo-name: "echo" parameters: - { in: "body", name: "body", schema: { type: "object" } } responses: 200: description: "Echo response" schema: { type: "object" } ``` See Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 or Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3 for more in depth information about how to use Mojolicious::Plugin::OpenAPI with a "full app". Even with a "lite app" it can be very useful to read those guides. Looking at the documentation for "x-mojo-to" in Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 can be especially useful. (The logic is the same for OpenAPIv2 and OpenAPIv3) ## DESCRIPTION Mojolicious::Plugin::OpenAPI is Mojolicious::Plugin that add routes and input/output validation to your Mojolicious application based on a OpenAPI (Swagger) specification. This plugin supports both version 2.0 and 3.x, though 3.x *might* have some missing features. Have a look at the "SEE ALSO" for references to plugins and other useful documentation. Please report in issues \ or open pull requests to enhance the 3.0 support. ## HELPERS ### openapi.spec ``` $hash = $c->openapi->spec($json_pointer) $hash = $c->openapi->spec("/info/title") $hash = $c->openapi->spec; ``` Returns the OpenAPI specification. A JSON Pointer can be used to extract a given section of the specification. The default value of `$json_pointer` will be relative to the current operation. Example: ``` { "paths": { "/pets": { "get": { // This datastructure is returned by default } } } } ``` ### openapi.validate ``` @errors = $c->openapi->validate; ``` Used to validate a request. `@errors` holds a list of JSON::Validator::Error objects or empty list on valid input. Note that this helper is only for customization. You probably want "openapi.valid\_input" in most cases. ### openapi.valid\_input ``` $c = $c->openapi->valid_input; ``` Returns the Mojolicious::Controller object if the input is valid or automatically render an error document if not and return false. See "SYNOPSIS" for example usage. ## HOOKS Mojolicious::Plugin::OpenAPI will emit the following hooks on the application object. ### openapi\_routes\_added Emitted after all routes have been added by this plugin. ``` $app->hook(openapi_routes_added => sub { my ($openapi, $routes) = @_; for my $route (@$routes) { ... } }); ``` This hook is EXPERIMENTAL and subject for change. ## RENDERER This plugin register a new handler called `"openapi"`. The special thing about this handler is that it will validate the data before sending it back to the user agent. Examples: ``` $c->render(json => {foo => 123}); # without validation $c->render(openapi => {foo => 123}); # with validation ``` This handler will also use "renderer" to format the output data. The code below shows the default "renderer" which generates JSON data: ``` $app->plugin( OpenAPI => { renderer => sub { my ($c, $data) = @_; return Mojo::JSON::encode_json($data); } } ); ``` ## ATTRIBUTES ### route ``` $route = $openapi->route; ``` The parent Mojolicious::Routes::Route object for all the OpenAPI endpoints. ### validator ``` $jv = $openapi->validator; ``` Holds either a JSON::Validator::Schema::OpenAPIv2 or a JSON::Validator::Schema::OpenAPIv3 object. ## METHODS ### register ``` $openapi = $openapi->register($app, \%config); $openapi = $app->plugin(OpenAPI => \%config); ``` Loads the OpenAPI specification, validates it and add routes to `$app`. It will also set up "HELPERS" and adds a before\_render hook for auto-rendering of error documents. The return value is the object instance, which allow you to access the "ATTRIBUTES" after you load the plugin. `%config` can have: *coerce* See "coerce" in JSON::Validator for possible values that `"coerce"` can take. Default: booleans,numbers,strings The default value will include "defaults" in the future, once that is stable enough. *default\_response* Instructions for "add\_default\_response\_schema" in JSON::Validator::Schema::OpenAPIv2. (Also used for OpenAPIv3) *format* Set this to a default list of file extensions that your API accepts. This value can be overwritten by "x-mojo-to" in Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2. This config parameter is EXPERIMENTAL and subject for change. *log\_level* `"log_level"` is used when logging invalid request/response error messages. Default: "warn". *op\_spec\_to\_route* `"op_spec_to_route"` can be provided if you want to add route definitions without using "x-mojo-to". Example: ``` $app->plugin(OpenAPI => {op_spec_to_route => sub { my ($plugin, $op_spec, $route) = @_; # Here are two ways to customize where to dispatch the request $route->to(cb => sub { shift->render(openapi => ...) }); $route->to(ucfirst "$op_spec->{operationId}#handle_request"); }}); ``` This feature is EXPERIMENTAL and might be altered and/or removed. *plugins* A list of OpenAPI classes to extend the functionality. Default is: Mojolicious::Plugin::OpenAPI::Cors, Mojolicious::Plugin::OpenAPI::SpecRenderer and Mojolicious::Plugin::OpenAPI::Security. ``` $app->plugin(OpenAPI => {plugins => [qw(+Cors +SpecRenderer +Security)]}); ``` You can load your own plugins by doing: ``` $app->plugin(OpenAPI => {plugins => [qw(+SpecRenderer My::Cool::OpenAPI::Plugin)]}); ``` *renderer* See "RENDERER". *route* `"route"` can be specified in case you want to have a protected API. Example: ``` $app->plugin(OpenAPI => { route => $app->routes->under("/api")->to("user#auth"), url => $app->home->rel_file("cool.api"), }); ``` *skip\_validating\_specification* Used to prevent calling "errors" in JSON::Validator::Schema::OpenAPIv2 for the specification. *spec\_route\_name* Name of the route that handles the "basePath" part of the specification and serves the specification. Defaults to "x-mojo-name" in the specification at the top level. *spec, url* See "schema" in JSON::Validator for the different `"url"` formats that is accepted. `"spec"` is an alias for "url", which might make more sense if your specification is written in perl, instead of JSON or YAML. Here are some common uses: ``` $app->plugin(OpenAPI => {url => $app->home->rel_file('openapi.yaml')); $app->plugin(OpenAPI => {url => 'https://example.com/swagger.json'}); $app->plugin(OpenAPI => {spec => JSON::Validator::Schema::OpenAPIv3->new(...)}); $app->plugin(OpenAPI => {spec => {swagger => "2.0", paths => {...}, ...}}); ``` *version\_from\_class* Can be used to overridden `"/info/version"` in the API specification, from the return value from the `VERSION()` method in `"version_from_class"`. Defaults to the current `$app`. This can be disabled by setting the "version\_from\_class" to zero (0). ## AUTHORS ### Project Founder Jan Henning Thorsen - `"jhthorsen@cpan.org"` ### Contributors - • Bernhard Graf \ - • Doug Bell \ - • Ed J \ - • Henrik Andersen \ - • Henrik Andersen \ - • Ilya Rassadin \ - • Jan Henning Thorsen \ - • Jan Henning Thorsen \ - • Ji-Hyeon Gim \ - • Joel Berger \ - • Krasimir Berov \ - • Lars Thegler \ - • Lee Johnson \ - • Linn-Hege Kristensen \ - • Manuel \ - • Martin Renvoize \ - • Mohammad S Anwar \ - • Nick Morrott \ - • Renee \ - • Roy Storey \ - • SebMourlhou \<35918953+SebMourlhou@users.noreply.github.com\> - • SebMourlhou \ - • SebMourlhou \ - • Søren Lund \ - • Stephan Hradek \ - • Stephan Hradek \ ## COPYRIGHT AND LICENSE Copyright (C) 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. ## SEE ALSO - • Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 Guide for how to use this plugin with OpenAPI version 2.0 spec. - • Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3 Guide for how to use this plugin with OpenAPI version 3.0 spec. - • Mojolicious::Plugin::OpenAPI::Cors Plugin to add Cross-Origin Resource Sharing (CORS). - • Mojolicious::Plugin::OpenAPI::Security Plugin for handling security definitions in your schema. - • Mojolicious::Plugin::OpenAPI::SpecRenderer Plugin for exposing your spec in human readable or JSON format. - • \ Official OpenAPI website.