ci(openapi): Improve OpenAPI checks

.github/workflows/openapi-ci.yaml

@@ -0,0 +1,122 @@
+name: OpenAPI checks
+
+on:
+    pull_request:
+    push:
+        branches:
+            - master
+
+jobs:
+    lint:
+        name: Lint specification
+        runs-on: ubuntu-latest
+
+        steps:
+            - uses: actions/checkout@v6
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: "npm"
+                  cache-dependency-path: "package-lock.json"
+
+            - name: Enable corepack
+              run: corepack enable
+
+            - name: Install dependencies
+              run: npm ci --force
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+            - name: Lint with Redocly
+              run: npm run openapi:lint:redocly -- --format=github-actions
+
+            - name: Lint with Spectral
+              run: npm run openapi:lint:spectral -- --format=github-actions
+
+            - name: Lint YAML style
+              run: npm run openapi:lint:yaml
+
+    build:
+        name: Build bundled specification
+        runs-on: ubuntu-latest
+        needs: lint
+
+        steps:
+            - uses: actions/checkout@v6
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: "npm"
+                  cache-dependency-path: "package-lock.json"
+
+            - name: Enable corepack
+              run: corepack enable
+
+            - name: Install dependencies
+              run: npm ci --force
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+            - name: Build bundles
+              run: npm run openapi:build
+
+            - name: Upload bundles
+              uses: actions/upload-artifact@v4
+              with:
+                  name: openapi-bundles
+                  path: |
+                      static/api/openapi.json
+                      static/api/openapi.yaml
+                  retention-days: 1
+
+    validate:
+        name: Validate bundled specification
+        runs-on: ubuntu-latest
+        needs: [lint, build]
+
+        steps:
+            - uses: actions/checkout@v6
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: "npm"
+                  cache-dependency-path: "package-lock.json"
+
+            - name: Enable corepack
+              run: corepack enable
+
+            - name: Install dependencies
+              run: npm ci --force
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+            - name: Download bundles
+              uses: actions/download-artifact@v4
+              with:
+                  name: openapi-bundles
+                  path: static/api/
+
+            - name: Validate YAML bundle
+              run: npx redocly lint static/api/openapi.yaml
+
+            - name: Validate JSON bundle
+              run: npx redocly lint static/api/openapi.json
+
+            - name: Check bundle sizes
+              run: |
+                  JSON_SIZE=$(stat -f%z static/api/openapi.json 2>/dev/null || stat -c%s static/api/openapi.json)
+                  YAML_SIZE=$(stat -f%z static/api/openapi.yaml 2>/dev/null || stat -c%s static/api/openapi.yaml)
+                  echo "Bundle sizes:"
+                  echo "  JSON: $JSON_SIZE bytes"
+                  echo "  YAML: $YAML_SIZE bytes"
+                  if [ "$JSON_SIZE" -lt 1000 ] || [ "$YAML_SIZE" -lt 1000 ]; then
+                    echo "Error: Bundle files are suspiciously small"
+                    exit 1
+                  fi
+                  echo "✓ Bundles have valid sizes"

.gitignore

@@ -24,8 +24,6 @@ sources/api/*
 apify-api.yaml
 static/api
 apify-docs-theme/package-lock.json
-codegen/*/generated/
-codegen/*/go.sum
 .github/styles/Microsoft
 .github/styles/write-good
 sources/academy/**/exercises/storage

.spectral.yaml

@@ -0,0 +1,15 @@
+# Configuration of Spectral, a tool for linting OpenAPI specification.
+extends:
+  - 'spectral:oas'
+
+rules:
+  # Allow nullable fields in examples - these reference schemas with nullable properties
+  oas3-valid-media-example: off
+  oas3-valid-schema-example: off
+
+overrides:
+  - files:
+      - apify-api/openapi/openapi.yaml
+    rules:
+      # Allow $ref for tags field - Redocly bundles it during build
+      oas3-schema: off

apify-api/openapi/components/schemas/actor-builds/Build.yaml

@@ -21,12 +21,12 @@ properties:
   startedAt:
     type: string
     format: date-time
-    example: '2019-11-30T07:34:24.202Z'
+    example: "2019-11-30T07:34:24.202Z"
   finishedAt:
     type: string
     format: date-time
     nullable: true
-    example: '2019-12-12T09:30:12.202Z'
+    example: "2019-12-12T09:30:12.202Z"
   status:
     $ref: ../common/ActorJobStatus.yaml
   meta:
@@ -65,15 +65,15 @@ properties:
     type: string
     example: 0.1.1
   actorDefinition:
-      allOf:
-        - $ref: "../actors/ActorDefinition.yaml"
-      nullable: true
+    allOf:
+      - $ref: ../actors/ActorDefinition.yaml
+    nullable: true
 example:
   id: HG7ML7M8z78YcAPEB
   actId: janedoe~my-actor
   userId: klmdEpoiojmdEMlk3
-  startedAt: '2019-11-30T07:34:24.202Z'
-  finishedAt: '2019-12-12T09:30:12.202Z'
+  startedAt: "2019-11-30T07:34:24.202Z"
+  finishedAt: "2019-12-12T09:30:12.202Z"
   status: SUCCEEDED
   meta:
     origin: WEB
@@ -97,37 +97,37 @@ example:
   readme: '# Magic Actor\nThis Actor is magic.'
   buildNumber: 0.1.1
   actorDefinition:
-      actorSpecification: 1
-      name: "exmpla-actor"
-      version: "1.0"
-      buildTag: "latest"
-      environmentVariables:
-          DEBUG_MODE: "false"
-      input:
-          type: "object"
-          properties:
-              prompt:
-                  type: "string"
-                  description: "The text prompt to generate completions for."
-              maxTokens:
-                  type: "integer"
-                  description: "The maximum number of tokens to generate."
-          required:
-              - prompt
-      storages:
-          dataset:
-              type: "object"
-              $schema: "http://json-schema.org/draft-07/schema#"
-              properties:
-                  id:
-                      type: "string"
-                      description: "Unique identifier for the generated text."
-                  text:
-                      type: "string"
-                      description: "The generated text output from the model."
-              required:
-                  - id
-                  - text
-      minMemoryMbytes: 512
-      maxMemoryMbytes: 2048
-      usesStandbyMode: false
+    actorSpecification: 1
+    name: exmpla-actor
+    version: "1.0"
+    buildTag: latest
+    environmentVariables:
+      DEBUG_MODE: "false"
+    input:
+      type: object
+      properties:
+        prompt:
+          type: string
+          description: The text prompt to generate completions for.
+        maxTokens:
+          type: integer
+          description: The maximum number of tokens to generate.
+      required:
+        - prompt
+    storages:
+      dataset:
+        type: object
+        $schema: "http://json-schema.org/draft-07/schema#"
+        properties:
+          id:
+            type: string
+            description: Unique identifier for the generated text.
+          text:
+            type: string
+            description: The generated text output from the model.
+        required:
+          - id
+          - text
+    minMemoryMbytes: 512
+    maxMemoryMbytes: 2048
+    usesStandbyMode: false

apify-api/openapi/components/schemas/actor-builds/BuildShort.yaml

@@ -18,11 +18,11 @@ properties:
   startedAt:
     type: string
     format: date-time
-    example: '2019-11-30T07:34:24.202Z'
+    example: "2019-11-30T07:34:24.202Z"
   finishedAt:
     type: string
     format: date-time
-    example: '2019-12-12T09:30:12.202Z'
+    example: "2019-12-12T09:30:12.202Z"
   usageTotalUsd:
     type: number
     example: 0.02