Documentation Driven Development

Documentation Driven Development

At adopting a new and growing trend, “documentation driven development” via “swagger” and now the newly updated specification, “OpenAPI 3”.

Documentation driven development (DDD) is not something new (some of its earliest concepts date back to 2011), but up until recently it never had an officially accepted name, nor an industry standard for the world to agree upon. It is the process of describing an API’s endpoints and what it expects as a request and should respond with. This enables a front-end team to easily use an API within their apps and mock the response.

Documentation driven development boils down to a two high level and basic principles:

  • Design the API first, then build it
    • The API design must adhere to the OpenAPI Specification (formerly known as Swagger)
    • The yaml file can be broken up with swagger-chunk
    • The finished result of the API design should be a Yaml or JSON file
    • The actual API routes should be built on what is documented in the design
    • The client, eg the browser, should communicate with the API via a generated file, built from a tool such as swagger-code-gen
  • An endpoint not documented should not exist
    • A JavaScript front-end engineer using a generated DDD API access file should not look outside of this file to access the API
    • As all routes must be documented, any other routes can be seen as not required &/or dangerous

Adhering to DDD simultaneously increases development speed whilst solving a growing issue regarding how the front-end and back-end teams both build and communicate. Further more this is not limited to company cross-team dynamics but also expandable to cross-company communications.

Looking to the future

DDD has given us some very big gains as described, but what could the future look like and how do we aim to streamline this process yet further.

Currently the API design must be written in a single Yaml file. When the API gets bigger than trivial the need to break the file down into sizable chunks becomes a must, this is where swagger-chunk comes in. swagger-chunk allows the developer to write many smaller and managable Yaml files which swagger-chunk then combines together into one.

Swagger-chunk is one step in the right direction, but it can be easy to get lost in a myriad of similar looking files. Further more, designing an API does not nesasarily depend on skill of a developer if there were an alternative to writing pure Yaml chunks…. Enter openapi-gui.

Openapi-gui is a graphical user interface to building the API design. The API designer does not require anything more than a web browser and technical knowledge on what a RESTfull API should be and deliver. In laymans terms, the API design can now be realised by a skilled technical product owner


Installing postman on linux


Server side rendering with phpv8/v8js on Ubuntu requires phpv8/v8js. Here is how to install the latest (at the time of writing) with php7.1.

Add the latest ppa from this guy:

Update the sources:

Install libv8:

Install and compile v8js

Optionally remove the files from the install from /tmp.

After this the SSR of the example vuejs app should work.

__dirname resolving to root of disk… /

Building an electron app you will find most of the examples refer to loading with something like:

The problem is, if you build with webpack.. then __dirname will actually resolve to the root of the disk.

To resolve this there is a simple hack/fix:

In your webpack config, add these two flags as false and things will start working.

Electron packager tutorial

Example electron app

This guy made a nice tutorial on electron with the code here, a perfect starting point if you’ve just arrived at electron

Install the dependencies to your system and app:

Adding the scripts to your package.json

And run


To create a package for debain, aka .deb

This guys has written a nice blog post on it:


Ubuntu/Linux Mint Open Office

I grew up with Windows and thus MS Office… As MS introduced the Ribbon feature, IMO things went downhill. The program got overly complex and a drain on resources, as such I came upon OpenOffice… great! An open source alternative to MS Office and it worked nicely.

Then a some years back, I started messing around with Dual Booting my machine, Windows on one side and Ubuntu on the other. But with Ubuntu came LibreOffice, which to this day just does not work cleanly and smoothly as OpenOffice does.

These days, triggered by the ultimate in shady operating systems, Windows 10, I no longer dual boot and instead only use Linux. As a developer I rarely need to use Office, so up until now I have put up with inadequacies of LibreOffice… but today when I actually had to write a document from scratch, enough was enough.

Installing OpenOffice on Linux:

  1. Remove LibreOffice:
  2. Clean up:
  3. Download the latest DEB from
  4. Untar the compressed file either via cli or right cliking on the tar and selecting ‘Extract here’
  5. Open a command line in the extracted folder
  6. Change dir to DEBS
  7. Install all the program files:
  8. Install all the desktop icons for OpenOffice:
  9. Done.


Apache files as not www-data

There used to be a pretty cool mod for apache that allowed it to run certain vhosts as someone other than www-data.

Unfortunately this mod has not been kept up to date and doesn’t work reliably on newer versions of Apache2. As such you are left with a dilema, either act as apache or add apache and yourself to a group who has rights to the files.

For a dev server the better option IMO is to allow devs to ssh in as apache and thus nothing else is required. Each dev can sync their files and everything just works nicely. The reason for this is the usual suspect, Windows. Although there is Cygwin which gives linux toolbox to Windows users, there is still no way around syncing between Linux and Windows and the permissions being correct. Windows and *nix file systems are just fundamentally different. Don’t believe me, try it out for yourself, either:

  1. Rsync a fileset from a linux server to a windows desktop. Now try work on them or sync them back or even try commit the changes to git.. no joy.
  2. Rsync a  fileset from a windows desktop to a linux server.. it is basically not possible yet to retain all the file permissions. Doesn’t matter which flags you add.

Back to the topic

NB: To see users and groups see this post: previous post

Create a new usergroup webdev and add the www-data user to it and then any other users you need in this group.

At this point you have a group apache and you can both write within it. Now in the folder with the files you want to work on and apache to server you need to apply a default group:

Next we can verify:


Last thing to do is to make sure, the group webdev has rwx rights on the files

Restore a destroyed USB drive

Please note: this deletes all data on the target device and requires a real OS (so no Macs or Windows 😉 ).

I enjoy trying out new Linux distrobutions from time to time, occasionally I destroy the odd USB stick as my knowledge on partition tables is not where I would like it to be. I found a series of commands that will restore a USB stick to its former glory (even when gparted or any other program says it’s basically bin worthy)

Install prerequisite:

Assuming the target USB is at /dev/sdb

(please check first with lsblk or gnome-disks or sudo fdisk -l and be sure you know what you are formatting)

Make sure the device has no mounted filesystem and unmount it if necessary, for example:

Destroy existing partition table:

Create new GPT:

Format as FAT32:

Check it:

Should output something like:

That’s it, your stick should be clean.

Multipart form breaks nodejs express expected format

Multi-part forms usually break express as the expected body is not present.. This is also true for a JS app posting to Node if the JS app builds a FormData object:

The above npm package fixes this. It acts as a middleware to auto format incoming requests into the nice body and file format you are expecting. In your press middleware loader add the following: