Use plugin only for rendering spec?

[christopherraa]

This is perhaps quite the edge-case, but bear with me.

Say you have three APIs:

• FooAPI, available at https://example.com/foo
• BarAPI, available at https://example.com/bar
• BazAPI, available at https://example.com/baz

These APIs are meant only to be accessed by OpenAPI-clients, with appropriate security measures for that kind of use. They are not meant to be directly accessed by end users (ie: developers).

Having the option of using SpecRenderer to render a html-representation of the API documentation would enable users to expose documentation for multiple APIs through one application tailored for that kind of use. This application would ideally just slurp the yaml/json-specs available one the abovementioned urls and present something human readable. This means that base_url in the rendered documentation would have to point to the location from which the spec was pulled. It would also mean that one would not want the plugin to also register routes for the endpoints found in the api specification that is loaded. Perhaps having skip_route_registration => 1 as an option to the OpenAPI plugin could help with the latter, and preserve_base_url => 1 or something could address the former?

I guess this issue is more of a braindump and an invitation for further discussion. Thoughts?

[jhthorsen]

I didn't do it quite as you described, but pretty close. Check out the commit for details, but...

• The spec is just "slurped", meaning basePath/servers/... will not be changed dynamically.
• No routes are registered, since that is done by Plugin::OpenAPI
• "skip_route_registration" and "preserve_base_url" are not needed, since you load Mojolicious::Plugin::OpenAPI::SpecRenderer directly as a plugin.

Hope this works for you!

[jhthorsen]

You might be interested in 9f845236048fd42017f099522362a0aa7a4db9ce as well, as it contains more templates that you can override to apply your own CSS/JavaScript.