SpecDoc

AI Enrichment

AI Enrichment uses Claude to automatically fill gaps in your OpenAPI spec — missing descriptions, request examples, error documentation, and more. Available on the Enterprise plan.

Enterprise feature

AI Enrichment is included in the Enterprise plan. Contact sales to enable it for your organisation.

What gets enriched

Operation descriptions

Before

description: ""

After

description: "Creates a new payment intent and returns a client secret for use with the SDK."

Parameter descriptions

Before

description: ""  # amount param

After

description: "The payment amount in the smallest currency unit (e.g. pence for GBP, cents for USD). Must be a positive integer."

Request body examples

Before

examples: {}

After

examples:
  CreatePaymentIntent:
    value:
      amount: 2000
      currency: gbp
      payment_method_types: [card]

Error response documentation

Before

400:
  description: Bad request

After

400:
  description: The request body is invalid.
  content:
    application/json:
      schema: { $ref: "#/components/schemas/Error" }
      examples:
        MissingAmount: { value: { error: "amount is required" } }

Enabling AI enrichment

Enable enrichment in your pipeline task. Enrichment runs after governance checks and before portal publish:

azure-pipelines.yml

- task: speclayer-publish@1
  inputs:
    specFile: 'openapi/api.yaml'
    projectSlug: 'payments-api'
    governancePolicy: 'strict'
    aiEnrichment: true
    aiEnrichmentMode: 'fill-gaps'   # Only fills missing fields
    publishPortal: true
  env:
    SPECLAYER_API_KEY: $(SPECLAYER_KEY)

Enrichment modes

fill-gaps

Only generates content for empty or missing fields. Never overwrites existing descriptions or examples. (Recommended)

enhance

Rewrites short or low-quality descriptions with more detailed ones. Existing content may be replaced.

full

Regenerates all descriptions and examples from scratch. Use with caution — will overwrite everything.

Quality score

Each spec version gets a documentation quality score from 0–100, calculated from:

Signal	Weight
Operations with descriptions	30%
Parameters with descriptions	20%
Success responses with examples	20%
Error responses documented	15%
Request body examples present	15%

AI enrichment results are attached to the spec version and can be reviewed before publishing. Use aiEnrichmentApproval: manual in the pipeline to pause and require a human to approve the enriched spec before the portal is updated.

CI/CD Integration

KlusterAlert Overview