CI/CD documentation sync

Keep your API Portal documentation in step with your code. Instead of uploading a new OpenAPI spec by hand after every release, your CI/CD pipeline pushes the latest spec to Apiable through the Platform API, so the reference your developers read always matches what you shipped.

What does CI/CD documentation sync do?

It uploads your OpenAPI spec to Apiable from your pipeline and points a documentation entry at it. On each deploy, the published API reference on your portal updates itself, so it never drifts from your code.

The flow is the same whichever CI/CD system you use:

1. Your pipeline builds or fetches your current OpenAPI spec.
2. It authenticates to the Platform API with your client credentials.
3. It uploads the spec and updates the documentation entry by its id.
4. Your portal's API reference now shows the new spec.

How do I set it up with GitHub Actions?

Apiable publishes a GitHub Action that runs the whole flow. Reference apiable/apiable-github-actions@v2 and pass your credentials, your spec URL, and the documentation id.

- uses: apiable/apiable-github-actions@v2
  with:
    api_key: ${{ secrets.APIABLE_CLIENT_ID }}
    api_secret: ${{ secrets.APIABLE_CLIENT_SECRET }}
    api_url: https://api.apiable.io
    open_api_spec_url: https://your-service.example.com/openapi.json
    docid: your-documentation-entry-id

Store the client id and secret as GitHub repository secrets, never in the workflow file. Set api_url to your Apiable API base URL. The action downloads the spec at open_api_spec_url, uploads it to Apiable, and updates the entry named by docid. The version-pinned source of truth is the apiable/apiable-github-actions repository.

How does it authenticate?

The action exchanges your client id and secret for a Platform API access token, then calls the documentation endpoints with it. The token must carry the apiable/cicd scope, which authorizes the documentation routes.

apiable/cicd is one of the Platform API scopes, alongside apiable/platform and apiable/admin. A CI/CD credential needs only apiable/cicd.

Can I sync docs without GitHub Actions?

Yes. The action is a wrapper over the Platform API, so any pipeline that can call an HTTP API works. It updates a documentation entry with PATCH /api/docs/{docId}, sending the X-API-Version: 2024-09-25 header.

See the Platform API reference for the request body and the rest of the documentation endpoints.

Where does the documentation id come from?

From a documentation entry on a plan. On the plan's Documentation tab, set an entry's source to Continuous Delivery, save, and use that entry's id as the docid your pipeline updates.

A plan's documentation can be sourced four ways: manual upload, gateway sync, Continuous Delivery (CI/CD), or the API catalog. Continuous Delivery is the one a pipeline drives. See Attach documentation to a plan.

Where to next