chore: add CI check for openapi spec generation

Author: pedroslopez

.github/workflows/python_lint.yml

@@ -76,3 +76,47 @@ jobs:
 
       - name: Run mypy
         run: poetry run mypy --config-file mypy.ini airbyte_cdk
+
+  openapi-check:
+    name: OpenAPI Spec Check
+    runs-on: ubuntu-24.04
+    steps:
+      # Common steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Set up Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: "2.0.1"
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "poetry"
+      - name: Install dependencies
+        run: poetry install --all-extras
+
+      # Job-specific step(s):
+      - name: Generate OpenAPI spec
+        run: poetry run manifest-server generate-openapi
+
+      - name: Check for changes
+        id: git-diff
+        run: |
+          git diff --quiet && echo "No changes to commit" || echo "changes=true" >> $GITHUB_OUTPUT
+        shell: bash
+
+      - name: Fail if OpenAPI spec is outdated
+        if: steps.git-diff.outputs.changes == 'true'
+        run: |
+          echo "❌ OpenAPI spec is out of date!"
+          echo ""
+          echo "The manifest-server API models have been modified, but the OpenAPI spec hasn't been updated."
+          echo "The following files have changes:"
+          git diff --name-only
+          echo ""
+          echo "Please run the following command and commit the changes:"
+          echo ""
+          echo "  poetry run manifest-server generate-openapi"
+          echo ""
+          exit 1

airbyte_cdk/manifest_server/README.md

@@ -125,6 +125,18 @@ The generated OpenAPI specification is consumed by other applications and tools
 - Provide API documentation and validation
 - Enable integration with API development tools
 
+### Automated OpenAPI Spec Validation
+
+The project includes a GitHub Actions check that automatically verifies the OpenAPI spec is up-to-date whenever API models are modified. This prevents developers from forgetting to regenerate the spec after making changes to request/response types.
+
+If you modify any files in `airbyte_cdk/manifest_server/api_models/`, make sure to run:
+
+```bash
+poetry run manifest-server generate-openapi
+```
+
+The CI will fail if the committed OpenAPI spec doesn't match what would be generated from the current API models.
+
 ### Interactive API Documentation
 
 When running, interactive API documentation is available at:

airbyte_cdk/manifest_server/openapi.yaml

@@ -296,6 +296,10 @@ components:
           $ref: '#/components/schemas/Manifest'
         config:
           $ref: '#/components/schemas/ConnectorConfig'
+        context:
+          anyOf:
+          - $ref: '#/components/schemas/RequestContext'
+          - type: 'null'
       type: object
       required:
       - manifest
@@ -330,6 +334,10 @@ components:
           $ref: '#/components/schemas/Manifest'
         config:
           $ref: '#/components/schemas/ConnectorConfig'
+        context:
+          anyOf:
+          - $ref: '#/components/schemas/RequestContext'
+          - type: 'null'
       type: object
       required:
       - manifest
@@ -357,6 +365,10 @@ components:
           minimum: 1.0
           title: Stream Limit
           default: 100
+        context:
+          anyOf:
+          - $ref: '#/components/schemas/RequestContext'
+          - type: 'null'
       type: object
       required:
       - manifest
@@ -457,10 +469,29 @@ components:
       - manifest
       title: ManifestResponse
       description: Response containing a manifest.
+    RequestContext:
+      properties:
+        workspace_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Workspace Id
+        project_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Project Id
+      type: object
+      title: RequestContext
+      description: Optional context information for tracing and observability.
     ResolveRequest:
       properties:
         manifest:
           $ref: '#/components/schemas/Manifest'
+        context:
+          anyOf:
+          - $ref: '#/components/schemas/RequestContext'
+          - type: 'null'
       type: object
       required:
       - manifest
@@ -542,6 +573,7 @@ components:
           title: Pages
         slice_descriptor:
           anyOf:
+          - type: object
           - type: string
           - type: 'null'
           title: Slice Descriptor
@@ -601,6 +633,10 @@ components:
           minimum: 1.0
           title: Slice Limit
           default: 5
+        context:
+          anyOf:
+          - $ref: '#/components/schemas/RequestContext'
+          - type: 'null'
       type: object
       required:
       - manifest