Mojolic...enderer(3)

hey bestie 💖 welcome to Mojolic...enderer(3), a page from the User Contributed Perl Documentation crew. This is the manual for Mojolicious::Plugin::OpenAPI::SpecRenderer, and it's lowkey main character energy for OpenAPI specs.

✨ NAME ✨

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

🦋 SYNOPSIS 🦋

💅 With Mojolicious::Plugin::OpenAPI

Okay so you can wire this up with Mojolicious::Plugin::OpenAPI like this:

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

If you're wondering what %openapi_parameters can hold, peek at register in Mojolicious::Plugin::OpenAPI — it spills the tea. ✨

🌈 Standalone

And yes, it can also go full solo mode:

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 in "Standalone" mode if you just want to render the specification, and not add any API routes to your application. Slay.

Wanna override parts of the render? The TEMPLATING section below has the deets. 🫶

The human-readable format is focused 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 suggestions for enhancements at https://github.com/jhthorsen/mojolicious-plugin-openapi/issues. Not me being picky — they literally want your feedback, bestie. 💅

There's a demo at https://demo.convos.chat/api.html — go peek.

🫶 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 Mojolicious stash variable format to change the format to render. By default it renders the whole specification, but it can also render documentation for a given OpenAPI path. Iconic.

🎀 openapi.rich_text

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

Used to render the description in the specification with Text::Markdown if it is installed. If the module is not available, it will just return the text. No cap.

🔥 METHODS 🔥

💜 register

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

Adds the features mentioned in 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

For more deets on styling and markup structure, see the DATA section in the source code.

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. Obsessed with customization, honestly. 🦋

🌈 SEE ALSO 🌈

Mojolicious::Plugin::OpenAPI — that's the whole vibe.

---

okay that's the whole page, bestie 🫶 the footer tea is: perl v5.42.0, dated 2025-08-03, filed under Mojolic...enderer(3) — periodt 💖