A pipeline delivering an API document into a documentation portal

Publish OpenAPI from CI with one curl

Documentation that depends on somebody remembering to upload a file is out of date by the second release. The fix is to make publishing a step of the pipeline. With SelfDocHub it is one HTTP call. This post shows it for GitHub Actions and GitLab CI, and the mistakes that cost people an afternoon.

The request#

Each service has its own upload token, created when an administrator registers the service. The request sends the specification as the body, not wrapped in any envelope:

curl --fail-with-body -X POST "https://docs.example.com/api/v1/services/billing-api/spec" \
  -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @openapi.json

The format (OpenAPI 3, Swagger 2, OpenRPC, AsyncAPI or GraphQL) is detected from the document and locked at the first publish. --fail-with-body makes curl return a non-zero exit code on a 4xx or 5xx, so a rejected document fails the job instead of being ignored, and it still prints the reason.

GitHub Actions#

Store the token as a repository secret named DOCS_UPLOAD_TOKEN:

name: Publish API docs
on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate the OpenAPI file
        run: ./gradlew generateOpenApi   # or any command that writes openapi.json
      - name: Publish to SelfDocHub
        env:
          DOCS_UPLOAD_TOKEN: ${{ secrets.DOCS_UPLOAD_TOKEN }}
        run: |
          curl --fail-with-body -X POST "https://docs.example.com/api/v1/services/billing-api/spec" \
            -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
            -H "Content-Type: application/json" \
            --data-binary @openapi.json

GitLab CI#

Add DOCS_UPLOAD_TOKEN as a masked CI/CD variable:

publish-docs:
  stage: deploy
  image: curlimages/curl:latest
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - >
      curl --fail-with-body -X POST "https://docs.example.com/api/v1/services/billing-api/spec"
      -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN"
      -H "Content-Type: application/json"
      --data-binary @openapi.json

Previews for feature branches#

An optional branch query parameter names the documentation branch of the version. A version becomes the service's current one only when its branch is the service's main branch, so a preview never changes what everybody else reads:

curl --fail-with-body -X POST "https://docs.example.com/api/v1/services/billing-api/spec?branch=feature-x" \
  -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
  --data-binary @openapi.json

Reviewers can then switch the portal to that branch and read how the API will look after the change.

Pitfalls#

  • Use --data-binary, not -d. With -d, curl removes newlines when it reads a file, which silently turns a multi-line YAML or GraphQL document into one invalid line.
  • Publish from the main branch, and use ?branch= for previews of pull requests, so a half-finished change never becomes the current version.
  • Watch the size limit. The document size is limited by the instance (10 MiB by default). If you run Nginx in front, raise client_max_body_size to match.
  • Keep the token secret. It can publish for that one service and cannot be used to sign in. If it leaks, an administrator rotates it and the old one stops working at once.
  • A service has one format. Sending a GraphQL schema to a service that started as OpenAPI is rejected with 400.

GraphQL and introspection#

A GraphQL service accepts either the SDL file or the JSON introspection result. If your pipeline queries a live endpoint, you can pipe one curl into the other:

curl -sS https://billing.internal/graphql -H "Content-Type: application/json" -d @introspection-query.json \
  | curl --fail-with-body -X POST "https://docs.example.com/api/v1/services/billing-api/spec" \
      -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @-

Full details are in the Publishing a Specification and GraphQL Schemas pages.

Frequently asked questions

Why --data-binary and not -d?

With -d, curl strips newlines when it reads from a file, which silently corrupts a multi-line YAML or GraphQL document into one invalid line. --data-binary sends the file as it is.

Is it safe to publish on every build?

Yes. Publishing identical content on the main branch answers 200 and creates no new version.

Run it on your own infrastructure

The Free plan includes a license for one installation. Start with Docker in a few minutes, no credit card needed.