Self documenting API specifications

I wanted to prepare the API specification for the backend developers in the most efficient way possible. Elm code is quite self explanatory, unfortunately Elm language is not the best at introspection. My idea was to display the Model type and the Decoders in some page that other developers could use for documentation. Moreover I wanted to provide a simple interface to test the API’s payloads.

This is the simplest solution that I could think of

  1. Provide a list of input fields and button that would allow to test the API and have their payload going through the Elm decoders

This is the result:

These are two examples of screens with a successful API test and one with error:

The test area is created with Elm, the two grey areas at the bottom are generated with Javascript using this code:

<pre id="decoders"></pre>
<pre id="types"></pre>
<script type="text/javascript">
(function() {
function readTextFile(file, fn) {
var rawFile = new XMLHttpRequest();"GET", file, true);
rawFile.onreadystatechange = function() {
if (rawFile.readyState === 4) {
if (rawFile.status === 200 || rawFile.status === 0) {
var allText = rawFile.responseText;
return fn(allText);
readTextFile("/source/scripts/helpers/types.elm", function(allText) {
document.getElementById('types').innerHTML = allText.match(/-- DATA[\s\S]*/)[0];
readTextFile("/source/scripts/helpers/decoders.elm", function(allText) {
document.getElementById('decoders').innerHTML = allText.match(/-- DATA[\s\S]*/)[0];

types.elm and decoders.elm are accessible, in the development environment, through the webserver. So the above snippet is receiving them using XMLHttpRequest.

This is, for example, decoders.elm

module Helpers.Decoders exposing (..)import Json.Decode as Decode exposing (Decoder)
import Helpers.Types as Types
-- DATA DECODERS --originDecoder : Decoder Types.Origin
originDecoder = [ "origin" ] Decode.string



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store