inaka

Latest blog entries

/
Erlang and Elixir Factory Lite B.A.

A brief introduction about what was the Erlang Factory Conference in Buenos Aires for some Inaka team members

Jul 07 2017 : Euen Lopez

/
The Art of Writing a Blogpost

The Art of Writing a Blogpost

Apr 11 2017 : Matias Vera

/
SpellingCI: No more spelling mistakes in your markdown flies!

Feb 14 2017 : Felipe Ripoll

/
Fast reverse geocoding with offline-geocoder

Do you need a blazing fast reverse geocoder? Enter offline-geocoder!

Jan 18 2017 : Roberto Romero

/
Using Jayme to connect to the new MongooseIM REST services

MongooseIM has RESTful services!! Here I show how you can use them in an iOS application.

Dec 13 2016 : Sergio Abraham

/
20 Questions, or Maybe a Few More

20 Questions, or Maybe a Few More

Nov 16 2016 : Stephanie Goldner

/
The Power of Meeting People

Because conferences and meetups are not just about the technical stuff.

Nov 01 2016 : Pablo Villar

/
Finding the right partner for your app build

Sharing some light on how it is to partner with us.

Oct 27 2016 : Inaka

/
Just Play my Sound

How to easily play a sound in Android

Oct 25 2016 : Giaquinta Emiliano

/
Opening our Guidelines to the World

We're publishing our work guidelines for the world to see.

Oct 13 2016 : Brujo Benavides

/
Using NIFs: the easy way

Using niffy to simplify working with NIFs on Erlang

Oct 05 2016 : Hernan Rivas Acosta

/
Function Naming In Swift 3

How to write clear function signatures, yet expressive, while following Swift 3 API design guidelines.

Sep 16 2016 : Pablo Villar

/
Jenkins automated tests for Rails

How to automatically trigger rails tests with a Jenkins job

Sep 14 2016 : Demian Sciessere

/
Erlang REST Server Stack

A description of our usual stack for building REST servers in Erlang

Sep 06 2016 : Brujo Benavides

/
Replacing JSON when talking to Erlang

Using Erlang's External Term Format

Aug 17 2016 : Hernan Rivas Acosta

/
Gadget + Lewis = Android Lint CI

Integrating our Android linter with Github's pull requests

Aug 04 2016 : Fernando Ramirez and Euen Lopez

/
Passwordless login with phoenix

Introducing how to implement passwordless login with phoenix framework

Jul 27 2016 : Thiago Borges

/
Beam Olympics

Our newest game to test your Beam Skills

Jul 14 2016 : Brujo Benavides

/
Otec

Three Open Source Projects, one App

Jun 28 2016 : Andr├ęs Gerace

/
CredoCI

Running credo checks for elixir code on your github pull requests

Jun 16 2016 : Alejandro Mataloni

/
See all Inaka's blog posts >>

/
Cowboy Swagger

Carlos Andres Bola├▒os wrote this on August 19, 2015 under cowboy, cowboy-swagger, documentation, erlang, rest, swagger .

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 priv/swagger folder.
  • Add the new static contents to your Cowboy routes to be compiled.
  • Then, create the swagger.json file (manually) which the Swagger UI feeds on to create the pages, and put it within priv/swagger folder.

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

Because 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 trails_handler behaviour:

trails() ->
  Metadata =
    #{get =>
      #{tags => ["echo"],
        description => "Gets echo var",
        produces => ["text/plain"]
      },
      put =>
      #{tags => ["echo"],
        description => "Sets echo var",
        produces => ["text/plain"],
        parameters => [
          #{name => <<"echo">>,
            description => <<"Echo message">>,
            in => <<"path">>,
            required => false,
            type => <<"string">>}
        ]
      }
    },
  [trails:trail("/message/[:echo]",
                example_echo_handler,
                [], Metadata)].

2. Include cowboy_swagger in your app

First, you need to include cowboy_swagger_handler module in your list of trails to be compiled.

% Include cowboy_swagger_handler in the trails list
Trails =
  trails:trails([example_echo_handler,
                 example_description_handler,
                 cowboy_swagger_handler]),
% store them
trails:store(Trails),
% and then compile them
Dispatch = trails:single_host_compile(Trails),

The snippet of code above is usually placed when you start cowboy.

Then add cowboy_swagger to the list of apps to be loaded in your *.app.src file.

{application, example,
 [
  {description, "Cowboy Swagger Example."},
  {vsn, "0.1"},
  {applications,
   [kernel,
    stdlib,
    jiffy,
    cowboy,
    trails,
    cowboy_swagger
   ]},
  {modules, []},
  {mod, {example, []}},
  {registered, []},
  {start_phases, [{start_trails_http, []}]}
 ]
}.

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.