API Docs for Platform.sh

The original public API documentation site for Platform.sh was primarily produced by me. The specification was created by merging machine-generated API docs from multiple backend services with developer-facing documentation largely written by me.

The public API documentation was one of my largest projects while working at Platform.sh and comprises several different components, including:

A Python library for parsing and manipulating OpenAPI Specification (OAS) schemas.
A CLI tool for working with the OAS schema library and generating the final API documentation.
The actual content of the API documentation.

When I worked on this project, the extant tooling for manipulating and merging OAS schemas was fairly limited. Because we needed the features of OpenAPI Specification 3.0 to properly describe the API, I had to create a custom tool to meet the needs of the project.

The actual documentation generation process was fairly straightforward. First, the OAS schemas for each of the backend services were merged into a combined schema. Then, a template file representing all of the available fields for documentation annotations was extracted, and developer-facing documentation was written in the extracted template. Finally, the human-written documentation was merged into the combined machine-generated schema, and the resulting OpenAPI schema was pushed to the documentation site.

I’ve excerpted many of the snippets written by me from the API documentation, and they are included as a single PDF.