api-overlay-generator

name

api-overlay-generator

description

Generate OpenAPI overlay files for Seqera Platform API documentation. Use when working with API documentation updates, analyzing comparison overlays from Speakeasy, creating operations/parameters/schemas overlay files, or updating API documentation for new Platform versions. Triggers include requests to generate overlays, document new API endpoints, analyze API changes, or work with Seqera Platform OpenAPI specifications.

OpenAPI overlay generator for Seqera Platform API

This skill generates high-quality OpenAPI overlay files for documenting the Seqera Platform API according to established standards and conventions.

Deployment

CI/CD: .github/workflows/generate-openapi-overlays.yml | Invocation: Repository dispatch or manual

When to use this skill

Use this skill when:

• Analyzing Speakeasy comparison overlays to identify API changes
• Generating operations, parameters, or schemas overlay files
• Documenting new API endpoints or controllers
• Updating API documentation for a new Platform version
• Validating overlay files against documentation standards
• Working with Seqera Platform OpenAPI specifications

Core workflow

Phase 1: Analysis

When given a Speakeasy comparison overlay, analyze it to identify changes:

# Run the analysis script
python scripts/analyze_comparison.py path/to/comparison-overlay.yaml

This generates:

• Console output: Human-readable summary of changes
• JSON file: Programmatic analysis for automation ({filename}-analysis.json)

The analysis categorizes changes by:

• New endpoints (requiring full documentation)
• Modified endpoints (requiring updates)
• New schemas (requiring property descriptions)
• Tag/controller grouping

Phase 2: Generate overlay files

Based on the analysis, generate three overlay files for each affected feature area:

1. Operations overlay

Purpose: Document endpoint summaries and descriptions

Key principles:

• Summaries use verb-entity pattern: "List datasets", "Create pipeline"
• Summaries are sentence case, no period
• Descriptions are full sentences with periods
• Include workspace scope context where applicable

Example:

overlay: 1.0.0
info:
  title: Datasets operations overlay
  version: 1.89
actions:
  # ===== DATASETS - OPERATIONS =====

  - target: "$.paths./datasets.get.summary"
    update: "List datasets"

  - target: "$.paths./datasets.get.description"
    update: "Lists all datasets in a user context, enriched by `attributes`. Append `?workspaceId` to list datasets in a workspace context."

2. Parameters overlay

Purpose: Document path, query, and request body parameters

Key principles:

• Use EXACT standard descriptions for common parameters (see references/standards.md)
• Always include defaults in backticks
• End all descriptions with periods
• Specify accepted values for enums

CRITICAL: These parameters MUST use standard descriptions:

• workspaceId: "Workspace numeric identifier."
• offset: "Number of results to skip for pagination. Default: 0."
• max: "Maximum number of results to return. Default: {value}."

CRITICAL - Parameter Array Replacement Pattern:

When the comparison overlay contains a remove: true action followed by a parameter array update, you MUST preserve BOTH actions in your generated overlay:

1. First action: Remove the entire existing parameters array with remove: true
2. Second action: Replace with the complete new array including enriched descriptions

Why: Simply updating individual parameter descriptions will cause duplicates and validation errors. The entire parameters array must be removed before replacement.

Example - Comparison overlay shows:

- target: $["paths"]["/data-links/{dataLinkId}/browse"]["get"]["parameters"][*]
  remove: true
- target: $["paths"]["/data-links/{dataLinkId}/browse"]["get"]["parameters"]
  update:
    - name: dataLinkId
      in: path
      description: Data-link string identifier
      required: true
      schema:
        type: string
    - name: path
      in: query
      description: Resource path to browse
      # ... more params

Your generated overlay MUST include BOTH actions:

overlay: 1.0.0
info:
  title: Data-links parameters overlay
  version: 1.102.0
actions:
  # ===== DATA-LINKS PARAMETERS =====

  # Remove entire parameters array to prevent duplicates
  - target: "$.paths./data-links/{dataLinkId}/browse.get.parameters[*]"
    remove: true

  # Replace with complete array with enriched descriptions
  - target: "$.paths./data-links/{dataLinkId}/browse.get.parameters"
    update:
      - name: dataLinkId
        in: path
        description: "Data-link string identifier."
        required: true
        schema:
          type: string
      - name: path
        in: query
        description: "Resource path to browse. Default: `/` (root directory)."
        required: false
        schema:
          type: string
      # ... include ALL parameters from comparison with enriched descriptions

DO NOT do this (updating descriptions without removal):

# ❌ WRONG - This will create duplicate parameters and validation errors
- target: "$.paths./data-links/{dataLinkId}/browse.get.parameters[?(@.name=='dataLinkId')].description"
  update: "Data-link string identifier."
# Missing the removal action = duplicates!

Standard example (when comparison shows simple description updates, not array replacement):

overlay: 1.0.0
info:
  title: Datasets parameters overlay
  version: 1.89
actions:
  # ===== DATASETS PARAMETERS =====

  # ---- PATH PARAMETERS ----

  - target: "$.paths./datasets/{datasetId}.get.parameters[?(@.name=='datasetId')].description"
    update: "Dataset numeric identifier."

  # ---- QUERY PARAMETERS ----

  - target: "$.paths./datasets.get.parameters[?(@.name=='workspaceId')].description"
    update: "Workspace numeric identifier."

  - target: "$.paths./datasets.get.parameters[?(@.name=='max')].description"
    update: "Maximum number of results to return. Default: `20`."

3. Schemas overlay

Purpose: Document request/response object properties

Key principles:

• Include validation rules (max length, format, etc.)
• Note nullable fields explicitly
• Describe enum values with all options
• Use "Array of" prefix for arrays
• Where it can be inferred from Platform API controller source code, add required: true key to every required field in a request body object

Example:

overlay: 1.0.0
info:
  title: Datasets schemas overlay
  version: 1.89
actions:
  # ===== DATASETS SCHEMAS =====

  - target: "$.components.schemas.DatasetRequest.properties.name"
    update:
      type: string
      required: true
      description: "Dataset name. Maximum 255 characters."

  - target: "$.components.schemas.DatasetRequest.properties.description"
    update:
      type: string
      nullable: true
      description: "Optional dataset description. Can be `null`."

Phase 3: Validation

After generating overlay files, validate them:

# Structural validation
python scripts/validate_overlay.py path/to/overlay.yaml

# Standards compliance
python scripts/check_consistency.py path/to/overlay.yaml

Fix any errors or warnings before proceeding.

Documentation standards

MUST READ: See references/standards.md for complete style guide including:

• Terminology standards (data-links, resource path, Array of)
• Standard parameter descriptions (workspaceId, max, offset, etc.)
• Operation summary patterns (verb-entity format)
• Description formatting rules
• Enum and default value formatting

MUST READ: See references/overlay-patterns.md for:

• Template structures for each overlay type
• Common patterns for CRUD operations
• JSONPath targeting examples
• Complete examples of all property types

Critical rules

Overlay Files

• ✅ NEVER create overlay files with empty actions lists
• ❌ Do not create overlays with only comments and no actual update actions
• ✅ If a feature area has no changes, omit the overlay file entirely
• ❌ Empty overlays will break the workflow automation

Summaries

• ✅ Sentence case: "List datasets"
• ❌ Title case: "List Datasets"
• ✅ No period at end
• ❌ With period: "List datasets."
• ✅ Verb-entity pattern: "Create pipeline"

Descriptions

• ✅ Must end with period: "Lists all datasets."
• ❌ No period: "Lists all datasets"
• ✅ Full sentences with context
• ✅ Include scope info where applicable

Standard parameters

• ✅ Use EXACT descriptions from standards.md
• ❌ Never invent new wording for workspaceId, max, offset, etc.
• ✅ Include defaults in backticks: "Default: 0."

Terminology

• ✅ "data-links" (not "datalinks" or "data links")
• ✅ "resource path" (not "bucket path")
• ✅ "Array of" (not "List of")
• ✅ "Workspace numeric identifier" (not "Workspace ID")

Overlay file structure

Naming convention

{resource}-{type}-overlay-{version}.yaml

Examples:
- datasets-operations-overlay-1.89.yaml
- datasets-parameters-overlay-1.89.yaml
- datasets-schemas-overlay-1.89.yaml

File organization

Within each overlay file:

overlay: 1.0.0
info:
  title: {Resource} {type} overlay
  version: {version}
actions:
  # ===== {FEATURE} - {TYPE} =====

  # ---- {SECTION NAME} ----

  - target: "$.paths.{endpoint}.{method}.{property}"
    update: "{value}"

  # ---- {NEXT SECTION} ----

  - target: "$.paths.{endpoint}.{method}.{property}"
    update: "{value}"

Organization rules:

• Group by resource/controller (===== markers)
• Separate by operation or schema (---- markers)
• Follow logical order (List → Get → Create → Update → Delete)
• Keep related targets together

JSONPath patterns

Common patterns

# Operation summary
$.paths./datasets.get.summary

# Operation description
$.paths./datasets.get.description

# Path parameter by name
$.paths./datasets/{datasetId}.get.parameters[?(@.name=='datasetId')].description

# Query parameter by name
$.paths./datasets.get.parameters[?(@.name=='workspaceId')].description

# Request body description
$.paths./datasets.post.requestBody.description

# Schema property
$.components.schemas.DatasetRequest.properties.name

# Response description
$.paths./datasets.get.responses['200'].description

Generating overlays from comparison

CRITICAL - Preserve ALL Actions from Comparison Overlay:

Every single action defined in the comparison overlay MUST be preserved in your generated overlay files. No orphaned actions are allowed.

Requirements:

1. One-to-one mapping: For each action in the comparison overlay, there must be AT LEAST one corresponding action in the generated overlays
2. One-to-many mapping: Some comparison actions will map to TWO generated actions:
   • Comparison has remove: true followed by update → Generate BOTH removal and update actions
   • Example: Parameter array replacement requires both remove and update
3. Verification: Before finalizing, check that every action in the comparison overlay has a corresponding action in your generated overlays

Example:

# Comparison overlay has 2 actions:
- target: $["paths"]["/endpoint"]["get"]["parameters"][*]
  remove: true  # ← Action 1
- target: $["paths"]["/endpoint"]["get"]["parameters"]
  update: [...]  # ← Action 2

# Your generated overlay MUST have both:
- target: "$.paths./endpoint.get.parameters[*]"
  remove: true  # ← Corresponds to Action 1
- target: "$.paths./endpoint.get.parameters"
  update: [...]  # ← Corresponds to Action 2

When analyzing a comparison overlay:

1. Count all actions: Note the total number of actions in the comparison overlay
2. Identify new endpoints: These need ALL three overlay types (operations, parameters, schemas)
3. Group by tag/controller: Create one set of overlay files per resource (datasets, credentials, etc.)
4. Check for standard parameters: Use exact standard descriptions
5. Follow patterns: Use templates from overlay-patterns.md
6. Maintain consistency: Same entities use same phrasing throughout
7. Verify completeness: Ensure every comparison action is represented in your generated overlays

Quality checklist

Before finalizing overlay files:

• All summaries are sentence case
• No summaries end with periods
• All descriptions end with periods
• Standard parameters use exact standard descriptions
• Terminology is consistent (data-links, resource path, Array of)
• All defaults are in backticks: 0, 20, false
• All enum values are listed with backticks
• Deprecated endpoints have proper notices
• File names follow convention: {feature}-{type}-overlay-{version}.yaml
• JSONPath syntax is valid
• Validation scripts pass

Scripts reference

Analysis

• scripts/analyze_comparison.py: Parse comparison overlay and categorize changes
  • Input: Comparison overlay YAML
  • Output: Console report + JSON analysis file

Validation

• scripts/validate_overlay.py: Check overlay structure and JSONPath syntax

  • Input: Overlay file
  • Output: Errors and warnings

• scripts/check_consistency.py: Verify standards compliance

  • Input: Overlay file
  • Output: Consistency issues

Automation

• scripts/update_sidebar.py: Add new operations to sidebar.js

  • Input: sidebar.js + analysis JSON
  • Output: Updated sidebar with new entries

• scripts/extract-api-tables.mjs: Generate parameter tables for info pages

  • Input: Decorated spec (seqera-api-latest-decorated.yaml)
  • Output: YAML tables in docs/info/parameter-tables/

Common mistakes to avoid

1. Empty overlay files: NEVER create overlay files with no action items (only comments). Empty overlays break the workflow automation.
2. Orphaned comparison actions: EVERY action in the comparison overlay MUST have a corresponding action in your generated overlays. Check that nothing is missing.
3. Missing parameter array removal: When comparison shows remove: true + array update, you MUST include BOTH actions. Updating descriptions without removal causes duplicate parameters and validation errors.
4. Inconsistent parameter descriptions: Always use standards.md exact wording
5. Missing periods in descriptions: Descriptions are sentences
6. Title case summaries: Use sentence case only
7. Invented terminology: Use established terms only
8. Missing defaults: Always specify default values in backticks
9. Incomplete enum listings: List all accepted values
10. Vague descriptions: Include specifics (max length, format, constraints)

Working with permanent overlays

One overlay is applied to EVERY version:

1. servers-overlay.yaml: Adds servers block with API URLs

This lives in scripts/specs/ and should not be moved to archives.

Integration points

This skill integrates with:

• Speakeasy CLI: For overlay comparison and application
• GitHub Actions: Automated workflow triggering
• Claude Code: Local development and testing
• Docusaurus: Documentation regeneration
• Platform repo: Source of truth for base specs

Next steps after generation

After generating overlay files:

1. Validate: Run validation scripts
2. Review: Manually check for accuracy and completeness
3. Engineering review: Get technical accuracy confirmation
4. Consolidate: Merge all overlays into single comprehensive file
5. Apply: Generate new decorated spec
6. Regenerate: Update MDX documentation files
7. Update sidebar: Add new operation entries
8. Archive: Move version-specific consolidated overlay file to overlay_archives/
9. Clean up: Remove the old base spec, individual overlays, and other ephemeral files, leaving only the decorated spec, latest base spec, and servers-overlay.yaml in the specs folder.