oracular (3) Mojolicious::Plugin::OpenAPI::SpecRenderer.3pm.gz

NAME

       Mojolicious::Plugin::OpenAPI::SpecRenderer - Render OpenAPI specification

SYNOPSIS

   With Mojolicious::Plugin::OpenAPI
         $app->plugin(OpenAPI => {
           plugins                        => [qw(+SpecRenderer)],
           render_specification           => 1,
           render_specification_for_paths => 1,
           %openapi_parameters,
         });

       See "register" in Mojolicious::Plugin::OpenAPI for what %openapi_parameters might contain.

   Standalone
         use Mojolicious::Lite;
         plugin "Mojolicious::Plugin::OpenAPI::SpecRenderer";

         # Some specification to render
         my $petstore = app->home->child("petstore.json");

         get "/my-spec" => sub {
           my $c    = shift;
           my $path = $c->param('path') || '/';
           state $custom = JSON::Validator->new->schema($petstore->to_string)->schema->bundle;
           $c->openapi->render_spec($path, $custom);
         };

DESCRIPTION

       Mojolicious::Plugin::OpenAPI::SpecRenderer will enable Mojolicious::Plugin::OpenAPI to render the
       specification in both HTML and JSON format. It can also be used "Standalone" if you just want to render
       the specification, and not add any API routes to your application.

       See "TEMPLATING" to see how you can override parts of the rendering.

       The human readable format focus on making the documentation printable, so you can easily share it with
       third parties as a PDF. If this documentation format is too basic or has missing information, then please
       report in <https://github.com/jhthorsen/mojolicious-plugin-openapi/issues> suggestions for enhancements.

       See <https://demo.convos.chat/api.html> for a demo.

HELPERS

   openapi.render_spec
         $c = $c->openapi->render_spec;
         $c = $c->openapi->render_spec($json_path);
         $c = $c->openapi->render_spec($json_path, $openapi_v2_schema_object);
         $c = $c->openapi->render_spec("/user/{id}");

       Used to render the specification as either "html" or "json". Set the "stash" in Mojolicious variable
       "format" to change the format to render.

       Will render the whole specification by default, but can also render documentation for a given OpenAPI
       path.

   openapi.rich_text
         $bytestream = $c->openapi->rich_text($text);

       Used to render the "description" in the specification with Text::Markdown if it is installed. Will just
       return the text if the module is not available.

METHODS

   register
         $doc->register($app, $openapi, \%config);

       Adds the features mentioned in the "DESCRIPTION".

       %config is the same as passed on to "register" in Mojolicious::Plugin::OpenAPI. The following keys are
       used by this plugin:

       render_specification

       Render the whole specification as either HTML or JSON from "/:basePath".  Example if "basePath" in your
       specification is "/api":

         GET https://api.example.com/api.html
         GET https://api.example.com/api.json

       Disable this feature by setting "render_specification" to 0.

       render_specification_for_paths

       Render the specification from individual routes, using the OPTIONS HTTP method.  Example:

         OPTIONS https://api.example.com/api/some/path.json
         OPTIONS https://api.example.com/api/some/path.json?method=post

       Disable this feature by setting "render_specification_for_paths" to 0.

TEMPLATING

       Overriding templates is EXPERIMENTAL, but not very likely to break in a bad way.

       Mojolicious::Plugin::OpenAPI::SpecRenderer uses many template files to make up the human readable version
       of the spec. Each of them can be overridden by creating a file in your templates folder.

         mojolicious/plugin/openapi/layout.html.ep
         |- mojolicious/plugin/openapi/head.html.ep
         |  '- mojolicious/plugin/openapi/style.html.ep
         |- mojolicious/plugin/openapi/header.html.ep
         |  |- mojolicious/plugin/openapi/logo.html.ep
         |  '- mojolicious/plugin/openapi/toc.html.ep
         |- mojolicious/plugin/openapi/intro.html.ep
         |- mojolicious/plugin/openapi/resources.html.ep
         |  '- mojolicious/plugin/openapi/resource.html.ep
         |     |- mojolicious/plugin/openapi/human.html.ep
         |     |- mojolicious/plugin/openapi/parameters.html.ep
         |     '- mojolicious/plugin/openapi/response.html.ep
         |        '- mojolicious/plugin/openapi/human.html.ep
         |- mojolicious/plugin/openapi/references.html.ep
         |- mojolicious/plugin/openapi/footer.html.ep
         |- mojolicious/plugin/openapi/javascript.html.ep
         '- mojolicious/plugin/openapi/foot.html.ep

       See the DATA section in the source code for more details on styling and markup structure.

       <https://github.com/jhthorsen/mojolicious-plugin-openapi/blob/master/lib/Mojolicious/Plugin/OpenAPI/SpecRenderer.pm>

       Variables available in the templates:

         %= $serialize->($data_structure)
         %= $slugify->(@str)
         %= $spec->{info}{title}

       In addition, there is a logo in "header.html.ep" that can be overridden by either changing the static
       file "mojolicious/plugin/openapi/logo.png" or set "openapi_spec_renderer_logo" in stash to a custom URL.

SEE ALSO

       Mojolicious::Plugin::OpenAPI