Why you want to use Swagger/OpenAPI for your REST API

Berlin.pm, Bicycle.pm

15 minutes



Swagger is a specification of a REST API.
It is now the base of the Open API Initiative supported by a number of companies

What *you* have to do:
* Understand the spec and specify all your API endpoints (parameters, input and output schema)
* Each item of the spec can have a "description"

What does it give you in return:
* The spec and your descriptions are the public documentation - no need to seperately administrate docs that possibly get out of date
* A nice javascript frontend for manual testing, with OAuth2 support
* A plugin for your web framework (*), which creates the routes and does all the input/output validation, so you only have to care about the actual business logic.
* You can write it in YAML

You don't need to write the validation yourself, but it helps to understand how it is done. I'll show you an example and some pitfalls you should be aware of.

I created an example git repository I'll use in my talk:

(*) Currently Mojolicious and Dancer2 

[ Abstract - Talk ]