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