inaka

Latest blog entries

/
The Art of Writing a Blogpost

The Art of Writing a Blogpost

Mar 09 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

/
Thoughts on rebar3

Thoughts on rebar3

Jun 08 2016 : Hernán Rivas Acosta

/
See all Inaka's blog posts >>

/
Get your Swagger on

Iñaki Garay wrote this on June 23, 2015 under documentation, erlang, rest, swagger .

If you write or consume RESTful APIs and are not familiar with swagger.io, you are sorely missing out.

What exactly is Swagger? It's a representation of your RESTful API, which is presented as documentation in a beautiful and very clear webpage. Proper documentation decreases the number of assumptions made, reduces the friction between the frontend and backend teams and establishes a contract both can code against, ultimately allowing them to work in parallel and increasing team performance. Enough buzzwords?

In a nutshell, you represent your API in some format, and Swagger will generate a webpage presenting said documentation.

Our Erlang team was introduced to Swagger by the Ruby team, which benefits from the swagger-docs gem which automatically generates the representation directly from their web handler code. This goes beyond "self documenting code"!

Check out their demo and tell me it doesn't make you envious.

However, when working with Erlang and Cowboy there is no way to generate your API's representation automatically. Instead, we're going to write it manually. Before Swagger we used to use wikis, markdown files commited in the code repo, google docs, edoc, you name it. Despite having to write the API representation in some unsightly format by hand, the end result is vastly superior.

So, how do we go about it?

First of all you should decide how you are going to host Swagger's output, and how private it should be. We usually use cowboy for our Erlang web server, and put our erlang nodes behind nginx for the SSL certificate handling and haproxy for load balancing. This means that our Erlang nodes are not internet-facing and we can afford to expose an endpoint serving the documentation. Alternatively, you could have nginx serve it; after all, it's static content. Just make sure your setup doesn't generate a cross-server request.

You should download the latest Swagger UI release, since all we want is the static Swagger UI code, this folder is what we want.

We download that folder and put its content in our priv/swagger folder.

If you are going to use cowboy to serve it, you can configure your route dispatch accordingly:

start_cowboy() ->
  Port =
    application:get_env(
      our_application,
      http_port,
      8383
    ),
  ListenerCount =
    application:get_env(
      our_application,
      http_listener_count,
      10
    ),
  TransOpts = [{port, Port}],
  Routes =
    [ {'_'
      , [ { "/api-docs/[...]"
          , cowboy_static
          , {dir, "priv/swagger"}
          }
        , ... % your other routes
        ]
      }],
  Dispatch = cowboy_router:compile(Routes),
  Opts = [{env, [{dispatch, Dispatch}]}],

  cowboy:start_http(
    http_listener,
    ListenerCount,
    TransOpts,
    Opts
  ).

Now, it's time to create the swagger.json file which the Swagger UI feeds on to create the pages.

The swagger.json file goes in the same priv/swagger folder. A representation of a /status endpoint that returns 200 if our server is ok would look a bit like this:

{
  "swagger": "2.0",
  "info": {
    "title": "My Server API",
    "description":
      "DCN server application for
      Illumination Entertainment.",
    "version": "0.1.0"
  },
  "schemes": ["http"],
  "basePath": "/",
  "produces": ["application/json"],
  "paths": {
    "/status": {
      "get": {
        "summary": "API Status.",
        "description":
          "Returns the current
          status of the API.\n",
        "tags": [
          "DevOps"
        ],
        "responses": {
          "200": {
            "description": "Status Ok."
          }
        }
      }
    }
  },
  "definitions": {
    "Token": {
      "properties": {
        "token": {
          "type": "string",
          "description":
            "Authentication
            Token value."
        },
        "expires_in": {
          "type": "string",
          "format": "date-time",
          "description": "Expiration date."
        }
      }
    }
  }
}

There is much more one can specify in the swagger.json file, for complete documentation check out this.

Silly human, JSON's for machines!

Of course hand-writing a potentially large JSON document is no fun. Swagger provides a nifty web-based YAML editor, which can later be turned into the swagger.json file.

We hope this lessens the pain of documenting your APIs and helps you connect with your friendly client devs!