API documentation for Drupal developers

Decoupled Drupal, RESTful, and the whole microservice mania we live in gave us enormous power to scale our products and build beautiful and snappy interfaces. With the great power comes an even greater responsibility to keep the communication layer of our services — the APIs — consistent, reliable and well documented.

Consistency means that every new API added to the product should have the look and feel of the other API’s. The more the product grows, the more it is difficult to keep it consistent.

Reliability is also a big issue, especially in the microservice architecture. An API may go offline, or even worse, its schema may change in a way that may break the backward compatibility.

Documentation is an indispensable ingredient for any API. It tends to become outdated with time and every undocumented functionality will probably remain unused and wasted resource.

These problems are real and agile teams are dealing with them on a day-to-day basis. This session describe a solution using OpenAPI Specification to generate machine-readable doc files. The OpenAPI docs would then be fed into the CI scripts to ensure consistency and reliability before every deployment. The same files would be a source for human-readable documentation, statically generated during the same deployment process. That way, a single source of truth would tackle all of the above problems.

This is an advanced session, and it was meant for developers who already have experience building API's in Drupal 7, Drupal 8, or other PHP frameworks. It also targets software architects who have problems maintaining big and scary API's.