SpecDoc

Quickstart

Publish your first versioned OpenAPI spec and see it live on a developer portal in about 5 minutes.

5 min setup OpenAPI 3.0 or 3.1 Any CI/CD

Prerequisites

An OpenAPI 3.0+ spec file (YAML or JSON)
A CI/CD pipeline (Azure DevOps, GitHub Actions, GitLab CI, or Jenkins)
A SpecLayer account (get started free)

Step 1: Get your API key

In the SpecLayer app, go to Settings → API Keys and create a new key. Store it as a secret in your CI/CD environment. Never commit it to source control.

The API key grants write access to your specs and portals. Treat it like a password. Use a dedicated key per pipeline, not a personal key.

Step 2: Add SpecDoc to your pipeline

All platforms use @speclayer/cli via npx. No install step needed. Node.js 18+ is pre-installed on all major hosted runners.

GitHub Actions

.github/workflows/publish-spec.yml

name: Publish API Spec
on:
  push:
    branches: [main]
    paths: ['openapi/**']
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Publish to SpecLayer
        run: |
          npx @speclayer/cli publish \
            --spec openapi/api.yaml \
            --project payments-api \
            --environment production
        env:
          SPECLAYER_API_KEY: ${{ secrets.SPECLAYER_KEY }}

Azure DevOps

azure-pipelines.yml

steps:
  - checkout: self
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
  - script: |
      npx @speclayer/cli publish \
        --spec openapi/api.yaml \
        --project payments-api \
        --environment production
    displayName: 'Publish spec to SpecLayer'
    env:
      SPECLAYER_API_KEY: $(SPECLAYER_KEY)

GitLab CI

.gitlab-ci.yml

publish-spec:
  stage: deploy
  image: node:20-alpine
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes: [openapi/**]
  script:
    - npx @speclayer/cli publish
        --spec openapi/api.yaml
        --project payments-api
        --environment production
  # Add SPECLAYER_API_KEY in Settings > CI/CD > Variables

Step 3: Configure your project

The --project slug identifies your API project in SpecLayer. If it doesn't exist yet, it will be created automatically on the first publish.

CLI options

--spec         Path to your OpenAPI file (YAML or JSON)   [required]
--project      Project slug                                [required]
--environment  production | staging | dev                  (default: production)
--governance   standard | strict | off                     (default: standard)
--api-url      Override for self-hosted deployments

Step 4: Push and verify

Commit your pipeline changes and push. After the pipeline runs you'll see:

A new version appears in the Spec Registry under your project
Governance check results are printed to the pipeline log
Your developer portal URL is printed at the end of the step
If governance fails, the pipeline step exits with a non-zero code

Example pipeline output

✓ SpecLayer — publishing spec
  Project:     payments-api
  Environment: production
  Spec file:   openapi/api.yaml (v3.1)

✓ Governance check (strict policy)
  PASS  naming.path-kebab-case           (42 paths checked)
  PASS  security.requires-auth-header    (38/38 paths)
  WARN  docs.operation-description       (4 operations missing descriptions)
  PASS  breaking-change-detection        (0 breaking changes)

✓ Spec Registry — saved as version 14
✓ Developer portal — rebuilt in 3.2s
  Portal URL: https://app.speclayer.net/portal/payments-api

What's next

Spec Registry

Browse version history and compare diffs

Governance Rules

Write your own API design policies

Developer Portals

Learn about your hosted developer portal

AI Enrichment

Auto-generate missing descriptions