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_sizeto 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.
