# 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:

```bash
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`:

```yaml
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:

```yaml
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:

```bash
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:

```bash
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](/documentation/publishing-specifications) and
[GraphQL Schemas](/documentation/graphql-schemas) pages.

---
Source: https://selfdochub.com/blog/publish-openapi-from-ci-with-curl
