search

jhthorsen / mojolicious-plugin-openapi

OpenAPI / Swagger plugin for Mojolicious
54 stars 44 forks source link

Clarification in Synopsis #166

Closed linnhk closed 4 years ago

linnhk commented 4 years ago

Hi! As a junior developer I'm always looking for the available help that is out there when I'm using modules that are new to me. I just noticed that when I was trying to use the Mojolicious::Plugin::OpenAPI::SpecRenderer plugin, my application crashed after having copy-pasted the code from the synopsis. I then had to investigate and concluded that I was missing the required parameter url.

My suggestion would be to edit the synopsis code to include a full working example, or adding an explanation of what is expected of me to already know (which the code snippet is lacking). This would be very helpful to me, and maybe other inexperienced developers out there.

jhthorsen commented 4 years ago

Thanks for the feedback! I won't include a full working example, because it will be very hard to remember to keep up to date in the future. Instead I added a reference, like this:

=head1 SYNOPSIS

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

See L<Mojolicious::Plugin::OpenAPI/register> for what
C<%openapi_parameters> might contain.
linnhk commented 4 years ago

That's great! Thank you.