Deploying docs from API Platform

API Platform is an API-first PHP framework that allows you to create REST and GraphQL APIs using PHP classes, and automatically generates their documentation, based on the OpenAPI specification.

This guide walks you through how to deploy API documents generated by API Platform, and how to enrich and filter those to improve the reader experience.

If you are new to API Platform, check out their getting started guide.

Deploying docs from your local machine #

The following assumes your local machine is configured with PHP and API Platform.

1. Create and name your first API documentation. Then, retrieve the name and token of this documentation from the CI deployment settings page.

2. Install the Bump.sh CLI with npm as below, or use alternative options, with

     npm install -g bump-cli
   

3. Launch your local server with Docker or Symfony

4. Deploy your doc to Bump.sh with

     bump deploy https://localhost/docs.json \
    --doc my-documentation-name \
    --token my-documentation-token
   

That’s it! Enjoy the comfort of Bump.sh to browse through your API doc, and customize it to your needs.

Enriching documents #

By default, API Platform generates what can be considered a plain technical description of your API. Although it is robust and complete, it’s not enough for people discovering your API without any upfront knowledge about it, access to the code, or ability to test it extensively. Such documents require contextual information, and any appropriate adjustements.

API Platform lets you override, enrich and filter the generated OpenAPI documents, using PHP.

You can also accomplish this using OpenAPI’s Overlay specification, which can be convenient in all use cases where you do not want to change your PHP code base (e.g. when involving Technical Writers or Product Managers in writing docs).

The Bump.sh CLI supports Overlays. Technically, the bump overlay command will output a modified version of the [DEFINITION_FILE] (an OpenAPI or AsyncAPI document) by applying the operations described in the [OVERLAY_FILE] Overlay file to the original API document.

1. Create your Overlay document (see example use cases in Augmenting Generated OpenAPI Documents with Filters & Overlays), and name it overlays.json (YAML and JSON are both supported as inputs for the CLI).

2. Apply your Overlay document to the original API document

     bump overlay https://localhost/docs.json overlays.json > docs.updated.json
   

3. Deploy the resulting file to Bump.sh

     bump deploy docs.updated.json \
    --doc my-documentation-name \
    --token my-documentation-token
   

Note: The diff computation performed by Bump.sh to display the API changelog is done when the resulting file is deployed. If you need to compute the diff before applying Overlays (for instance when your Overlay document filters out some information), consider using the bump diff command and the GitHub Action.