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

Choose your CI/CD system:

Azure DevOps

azure-pipelines.yml

steps:
  - task: speclayer-publish@1
    inputs:
      specFile: 'openapi/api.yaml'
      projectSlug: 'payments-api'
      environment: 'production'
      governancePolicy: 'strict'
      publishPortal: true
    env:
      SPECLAYER_API_KEY: $(SPECLAYER_KEY)

GitHub Actions

.github/workflows/docs.yml

jobs:
  publish-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: speclayer/publish-action@v1
        with:
          spec-file: openapi/api.yaml
          project-slug: payments-api
          environment: production
          governance-policy: strict
          publish-portal: true
        env:
          SPECLAYER_API_KEY: ${{ secrets.SPECLAYER_KEY }}

GitLab CI

.gitlab-ci.yml

publish-docs:
  stage: deploy
  image: speclayer/cli:latest
  script:
    - speclayer publish
        --spec openapi/api.yaml
        --project payments-api
        --env production
        --policy strict
        --portal
  variables:
    SPECLAYER_API_KEY: $SPECLAYER_KEY

Step 3 — Configure your project

The projectSlug maps to a project in your SpecLayer workspace. If the project doesn't exist yet, it will be created automatically on the first run.

Key configuration options

specFile          Path to your OpenAPI file (YAML or JSON)
projectSlug       Unique identifier for this API project
environment       'production' | 'staging' | 'dev' (default: production)
governancePolicy  'strict' | 'standard' | 'off' (default: standard)
publishPortal     true | false — rebuild the developer portal (default: true)
breakingChange    'fail' | 'warn' | 'off' — how to handle breaking changes

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

Set up a custom domain for your portal

AI Enrichment

Auto-generate missing descriptions

Overview

Spec Registry