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
31           # "openapi_spec" can also be set in...
32           # - $app->defaults(openapi_spec => ...);
33           # - $route->to(openapi_spec => ...);
34           $c->stash(openapi_spec => JSON::Validator->new->schema($petstore->to_string)->bundle);
35
36           # render_spec() can be called with $openapi_path
37           $c->openapi->render_spec;
38         };
39

DESCRIPTION

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

HELPERS

58   openapi.render_spec
59         $c = $c->openapi->render_spec;
60         $c = $c->openapi->render_spec($openapi_path);
61         $c = $c->openapi->render_spec("/user/{id}");
62
63       Used to render the specification as either "html" or "json". Set the
64       "stash" in Mojolicious variable "format" to change the format to
65       render.
66
67       Will render the whole specification by default, but can also render
68       documentation for a given OpenAPI path.
69

METHODS

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

TEMPLATING

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

NAME

SYNOPSIS

DESCRIPTION

HELPERS

METHODS

TEMPLATING

SEE ALSO