Mojolicious::Plugin::OpenAPI::SpecRenderer - Render OpenAPI specification
$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.
%openapi_parameters
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_spec = JSON::Validator->new->schema($petstore->to_string)->bundle; $c->openapi->render_spec($path, $custom_spec); };
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 suggestions for enhancements.
See https://demo.convos.chat/api.html for a demo.
$c = $c->openapi->render_spec; $c = $c->openapi->render_spec($json_path); $c = $c->openapi->render_spec($json_path, \%custom_spec); $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.
$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.
$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:
%config
Render the whole specification as either HTML or JSON from "/:basePath". Example if basePath in your specification is "/api":
basePath
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
0
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.
render_specification_for_paths
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 overriden by either changing the static file "mojolicious/plugin/openapi/logo.png" or set "openapi_spec_renderer_logo" in stash to a custom URL.
Mojolicious::Plugin::OpenAPI
To install Mojolicious::Plugin::OpenAPI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious::Plugin::OpenAPI
CPAN shell
perl -MCPAN -e shell install Mojolicious::Plugin::OpenAPI
For more information on module installation, please visit the detailed CPAN module installation guide.