In a previous post about Swagger in Erlang, we had seen how to add a nice documentation to our RESTful APIs with Swagger, but following the long/tedious path:
- Download Swagger-UI and put it within your
- Add the new static contents to your Cowboy routes to be compiled.
- Then, create the
swagger.jsonfile (manually) which the Swagger UI feeds on to create the pages, and put it within
Well, forget about all that. Cowboy Swagger is an open source project built on top of Trails that integrates Swagger, so you can have a really nice Web documentation for your RESTful APIs in only a few simple steps.
Now, let’s see how simple and fast it is.
1. Document each Cowboy Handler
cowboy_swagger runs on top of
trails, the first thing that you have to do is document all about your handler within the trails metadata. Keep in mind that all fields defined within each method into the metadata must be compliant with the Swagger specification.
For example, suppose that you have
example_echo_handler, so it must implement the
trails/0 callback from
2. Include cowboy_swagger in your app
First, you need to include
cowboy_swagger_handler module in your list of trails to be compiled.
The snippet of code above is usually placed when you start
cowboy_swagger to the list of apps to be loaded in your
And that’s it, you got it. Now start your application and then you will have access to the API docs under the path
/api-docs. Supposing that you’re running the app on
localhost:8080, that will be http://localhost:8080/api-docs.
Finally, you’re welcome to check
cowboy_swagger sources and a full demonstrative example here.