Mojolicious::Plugin::OpenAPI::SpecRenderer(3pm)

1Mojolicious::Plugin::OpUesneArPIC:o:nStpreicbMRuoetjneoddleirPceeirro(lu3s)D:o:cPulmuegnitna:t:iOopnenAPI::SpecRenderer(3)
2
3
4

NAME

6       Mojolicious::Plugin::OpenAPI::SpecRenderer - Render OpenAPI
7       specification
8

SYNOPSIS

10   With Mojolicious::Plugin::OpenAPI
11         $app->plugin(OpenAPI => {
12           plugins                        => [qw(+SpecRenderer)],
13           render_specification           => 1,
14           render_specification_for_paths => 1,
15           %openapi_parameters,
16         });
17
18       See "register" in Mojolicious::Plugin::OpenAPI for what
19       %openapi_parameters might contain.
20
21   Standalone
22         use Mojolicious::Lite;
23         plugin "Mojolicious::Plugin::OpenAPI::SpecRenderer";
24
25         # Some specification to render
26         my $petstore = app->home->child("petstore.json");
27
28         get "/my-spec" => sub {
29           my $c    = shift;
30           my $path = $c->param('path') || '/';
31           state $custom_spec = JSON::Validator->new->schema($petstore->to_string)->bundle;
32           $c->openapi->render_spec($path, $custom_spec);
33         };
34

DESCRIPTION

36       Mojolicious::Plugin::OpenAPI::SpecRenderer will enable
37       Mojolicious::Plugin::OpenAPI to render the specification in both HTML
38       and JSON format. It can also be used "Standalone" if you just want to
39       render the specification, and not add any API routes to your
40       application.
41
42       See "TEMPLATING" to see how you can override parts of the rendering.
43
44       The human readable format focus on making the documentation printable,
45       so you can easily share it with third parties as a PDF. If this
46       documentation format is too basic or has missing information, then
47       please report in <https://github.com/jhthorsen/mojolicious-plugin-
48       openapi/issues> suggestions for enhancements.
49
50       See <https://demo.convos.by/api.html> for a demo.
51

HELPERS

53   openapi.render_spec
54         $c = $c->openapi->render_spec;
55         $c = $c->openapi->render_spec($json_path);
56         $c = $c->openapi->render_spec($json_path, \%custom_spec);
57         $c = $c->openapi->render_spec("/user/{id}");
58
59       Used to render the specification as either "html" or "json". Set the
60       "stash" in Mojolicious variable "format" to change the format to
61       render.
62
63       Will render the whole specification by default, but can also render
64       documentation for a given OpenAPI path.
65
66   openapi.rich_text
67         $bytestream = $c->openapi->rich_text($text);
68
69       Used to render the "description" in the specification with
70       Text::Markdown if it is installed. Will just return the text if the
71       module is not available.
72

METHODS

74   register
75         $doc->register($app, $openapi, \%config);
76
77       Adds the features mentioned in the "DESCRIPTION".
78
79       %config is the same as passed on to "register" in
80       Mojolicious::Plugin::OpenAPI. The following keys are used by this
81       plugin:
82
83       render_specification
84
85       Render the whole specification as either HTML or JSON from
86       "/:basePath".  Example if "basePath" in your specification is "/api":
87
88         GET https://api.example.com/api.html
89         GET https://api.example.com/api.json
90
91       Disable this feature by setting "render_specification" to 0.
92
93       render_specification_for_paths
94
95       Render the specification from individual routes, using the OPTIONS HTTP
96       method.  Example:
97
98         OPTIONS https://api.example.com/api/some/path.json
99         OPTIONS https://api.example.com/api/some/path.json?method=post
100
101       Disable this feature by setting "render_specification_for_paths" to 0.
102

TEMPLATING

104       Overriding templates is EXPERIMENTAL, but not very likely to break in a
105       bad way.
106
107       Mojolicious::Plugin::OpenAPI::SpecRenderer uses many template files to
108       make up the human readable version of the spec. Each of them can be
109       overridden by creating a file in your templates folder.
110
111         mojolicious/plugin/openapi/layout.html.ep
112         |- mojolicious/plugin/openapi/head.html.ep
113         |  '- mojolicious/plugin/openapi/style.html.ep
114         |- mojolicious/plugin/openapi/header.html.ep
115         |  |- mojolicious/plugin/openapi/logo.html.ep
116         |  '- mojolicious/plugin/openapi/toc.html.ep
117         |- mojolicious/plugin/openapi/intro.html.ep
118         |- mojolicious/plugin/openapi/resources.html.ep
119         |  '- mojolicious/plugin/openapi/resource.html.ep
120         |     |- mojolicious/plugin/openapi/human.html.ep
121         |     |- mojolicious/plugin/openapi/parameters.html.ep
122         |     '- mojolicious/plugin/openapi/response.html.ep
123         |        '- mojolicious/plugin/openapi/human.html.ep
124         |- mojolicious/plugin/openapi/references.html.ep
125         |- mojolicious/plugin/openapi/footer.html.ep
126         |- mojolicious/plugin/openapi/javascript.html.ep
127         '- mojolicious/plugin/openapi/foot.html.ep
128
129       See the DATA section in the source code for more details on styling and
130       markup structure.
131
132       <https://github.com/jhthorsen/mojolicious-plugin-openapi/blob/master/lib/Mojolicious/Plugin/OpenAPI/SpecRenderer.pm>
133
134       Variables available in the templates:
135
136         %= $serialize->($data_structure)
137         %= $slugify->(@str)
138         %= $spec->{info}{title}
139
140       In addition, there is a logo in "header.html.ep" that can be overriden
141       by either changing the static file
142       "mojolicious/plugin/openapi/logo.png" or set
143       "openapi_spec_renderer_logo" in stash to a custom URL.
144

NAME

SYNOPSIS

DESCRIPTION

HELPERS

METHODS

TEMPLATING

SEE ALSO