File Coverage

blib/lib/Mojolicious/Plugin/OpenAPI/SpecRenderer.pm

Criterion	Covered	Total	%
statement	94	94	100.0
branch	36	40	90.0
condition	23	29	79.3
subroutine	20	20	100.0
pod	1	1	100.0
total	174	184	94.5

package Mojolicious::Plugin::OpenAPI::SpecRenderer;
use Mojo::Base 'Mojolicious::Plugin';

use JSON::Validator;
use Mojo::JSON;
use Scalar::Util qw(blessed);

use constant DEBUG    => $ENV{MOJO_OPENAPI_DEBUG} || 0;
use constant MARKDOWN => eval 'require Text::Markdown;1';

sub register {
  my ($self, $app, $config) = @_;

  $app->defaults(openapi_spec_renderer_logo        => '/mojolicious/plugin/openapi/logo.png');
  $app->defaults(openapi_spec_renderer_theme_color => '#508a25');

  $self->{standalone} = $config->{openapi} ? 0 : 1;
  $app->helper('openapi.render_spec' => sub { $self->_render_spec(@_) });
  $app->helper('openapi.rich_text'   => \&_helper_rich_text);

  # EXPERIMENTAL
  $app->helper('openapi.spec_iterator' => \&_helper_iterator);

  unless ($app->{'openapi.render_specification'}++) {
    push @{$app->renderer->classes}, __PACKAGE__;
    push @{$app->static->classes},   __PACKAGE__;
  }

  $self->_register_with_openapi($app, $config) unless $self->{standalone};
}

sub _helper_iterator {
  my ($c, $obj) = @_;
  return unless $obj;

  unless ($c->{_helper_iterator}{$obj}) {
    my $x_re = qr{^x-};
    $c->{_helper_iterator}{$obj}
      = [map { [$_, $obj->{$_}] } sort { lc $a cmp lc $b } grep { !/$x_re/ } keys %$obj];
  }

  my $items = $c->{_helper_iterator}{$obj};
  my $item  = shift @$items;
  delete $c->{_helper_iterator}{$obj} unless $item;
  return $item ? @$item : ();
}

sub _register_with_openapi {
  my ($self, $app, $config) = @_;
  my $openapi = $config->{openapi};

  if ($config->{render_specification} // 1) {
    my $spec_route = $openapi->route->get(
      '/',
      [format => [qw(html json)]],
      {format => undef},
      sub { shift->openapi->render_spec(@_) }
    );
    my $name = $config->{spec_route_name} || $openapi->validator->get('/x-mojo-name');
    $spec_route->name($name) if $name;
  }

  if ($config->{render_specification_for_paths} // 1) {
    $app->plugins->once(openapi_routes_added => sub { $self->_add_documentation_routes(@_) });
  }
}

sub _add_documentation_routes {
  my ($self, $openapi, $routes) = @_;
  my %dups;

  for my $route (@$routes) {
    my $route_path = $route->to_string;
    next if $dups{$route_path}++;

    my $openapi_path = $route->to->{'openapi.path'};
    my $doc_route
      = $openapi->route->options($route->pattern->unparsed, {'openapi.default_options' => 1});
    $doc_route->to(cb => sub { $self->_render_spec(shift, $openapi_path) });
    $doc_route->name(join '_', $route->name, 'openapi_documentation')              if $route->name;
    warn "[OpenAPI] Add route options $route_path (@{[$doc_route->name // '']})\n" if DEBUG;
  }
}

sub _helper_rich_text {
  return Mojo::ByteStream->new(MARKDOWN ? Text::Markdown::markdown($_[1]) : $_[1]);
}

sub _render_partial_spec {
  my ($self, $c, $path, $custom) = @_;
  my $method    = $c->param('method');
  my $validator = $custom || Mojolicious::Plugin::OpenAPI::_self($c)->validator;

  return $c->render(json => {errors => [{message => 'No spec defined.'}]}, status => 404)
    unless my $schema = $validator->get([paths => $path, $method ? ($method) : ()]);

  return $c->render(
    json => {
      '$schema'   => 'http://json-schema.org/draft-04/schema#',
      title       => $validator->get([qw(info title)])       || '',
      description => $validator->get([qw(info description)]) || '',
      %{$validator->bundle({schema => $schema})->data},
      $method ? (parameters => $validator->parameters_for_request([$method, $path])) : (),
    }
  );
}

sub _render_spec {
  my ($self, $c, $path, $custom) = @_;
  return $self->_render_partial_spec($c, $path, $custom) if $path;

  my $openapi   = $custom || $self->{standalone} ? undef : Mojolicious::Plugin::OpenAPI::_self($c);
  my $format    = $c->stash('format') || 'json';
  my $validator = $custom;

  if (!$validator and $openapi) {
    $validator = $openapi->{bundled} ||= $openapi->validator->bundle;
    $validator->base_url($c->req->url->to_abs->path($c->url_for($validator->base_url->path)));
  }

  return $c->render(json => {errors => [{message => 'No specification to render.'}]}, status => 500)
    unless $validator;

  my $operations = $validator->routes->each(sub {
    my $path_item = $_;
    $path_item->{op_spec} = $validator->get([paths => @$path_item{qw(path method)}]);
    $path_item->{operation_id} //= '';
    $path_item;
  });

  return $c->render(json => $validator->data) unless $format eq 'html';
  return $c->render(
    base_url   => $validator->base_url,
    handler    => 'ep',
    template   => 'mojolicious/plugin/openapi/layout',
    operations => [sort { $a->{operation_id} cmp $b->{operation_id} } @$operations],
    serialize  => \&_serialize,
    slugify    => sub {
      join '-', map { s/\W/-/g; lc } map {"$_"} @_;
    },
    spec => $validator->data,
  );
}

sub _serialize { Mojo::JSON::encode_json(@_) }

1;

=encoding utf8

=head1 NAME

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

=head1 SYNOPSIS

=head2 With Mojolicious::Plugin::OpenAPI

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

See L for what
C<%openapi_parameters> might contain.

=head2 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);
  };

=head1 DESCRIPTION

L will enable
L to render the specification in both HTML and
JSON format. It can also be used L if you just want to render
the specification, and not add any API routes to your application.

See L 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
L
suggestions for enhancements.

See L for a demo.

=head1 HELPERS

=head2 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
L 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.

=head2 openapi.rich_text

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

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

=head1 METHODS

=head2 register

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

Adds the features mentioned in the L.

C<%config> is the same as passed on to
L. The following keys are used by this
plugin:

=head3 render_specification

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

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

Disable this feature by setting C to C<0>.

=head3 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 C to C<0>.

=head1 TEMPLATING

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

L 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.

L

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 L to a
custom URL.

=head1 SEE ALSO

L

=cut

__DATA__