view release on metacpan or  search on metacpan

devdata/https_mojolicious.io_blog_2017_12_22_day-22-how-to-build-a-public-rest-api  view on Meta::CPAN

of documenting as well as testing. I often say that if you can't document
(describe) the API/method/whatever, something is wrong and you should reconsider
what you're coding. Documenting an API on the other hand is awful in my opinion,
especially during rapid prototyping/developing where it's hard to keep the
code and documentation up to date.</p>

<p>So how does OpenAPI fix this? Since the input/ouput Perl code is generated
<em>from</em> the OpenAPI Specification, you know that the backend is always running
code accordingly to the specification. Also, since the documentation you
generate is not hand written, but generated from the same OpenAPI document you
can with certainty know that the code the server is running, is in sync with
the documentation.</p>

<p>By &quot;generated code&quot; I don&#39;t just mean the routes/endpoints, but also input and
output validation. This means that when any data has made it through to your
controller action, you know that the data is valid. On the other side, the
consumer (let&#39;s say a JavaScript that cares about the difference between an
integer and string) will know that it has received the correct data, since
invalid output will result in a
<a href="https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#5xx_Server_Error">500 - Internal Server Error</a>.</p>