Recipe: Sync Your OpenAPI Spec

Import an OpenAPI 3.x spec and Syntext generates endpoint pages — request/response schemas, code samples, and an interactive try-it playground. This recipe keeps the spec in sync automatically.

One-Time Import

Point Syntext at a spec URL or upload the document:

curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi \
-H "Authorization: Bearer $SYNTEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://api.acme.com/openapi.json" }'

curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi \
-H "Authorization: Bearer $SYNTEXT_API_KEY" \
-H "Content-Type: application/json" \
-d "{ \"spec\": $(cat openapi.json) }"

Generated endpoint pages appear under your API reference tab after the next build.

Auto-Sync on Release

Re-push the spec whenever your API ships. In GitHub Actions:

name: Sync API docs
on:
  push:
    branches: [main]
    paths: ['openapi.json']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Push spec to Syntext
        run: |
          curl -fsS -X POST https://api.syntext.dev/v1/projects/${{ vars.SYNTEXT_PROJECT_ID }}/openapi \
            -H "Authorization: Bearer ${{ secrets.SYNTEXT_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "{\"spec\": $(cat openapi.json)}"

Inspecting What's Imported

# List imported specs
curl https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi/specs \
  -H "Authorization: Bearer $SYNTEXT_API_KEY"

# List generated endpoints
curl https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi/endpoints

To remove a spec and its generated pages: DELETE /v1/projects/{projectId}/openapi.

Combining with Hand-Written Content

Generated pages cover the what; write guides for the why. Link generated endpoint pages from your guides, and use annotation coverage to make sure code-level docs keep pace too.