[3/4] docs: show each request body's example in the API reference

.github/workflows/ci.yml

@@ -36,6 +36,9 @@ jobs:
       - name: Smoke tests
         run: pnpm test:smoke
 
+      - name: Request examples
+        run: pnpm test:examples
+
       - name: Install reference renderer
         working-directory: .shins
         run: npm ci --omit=dev --no-audit --no-fund

build-docs.sh

@@ -18,12 +18,17 @@ mkdir -p "$DOCS_DIR"
 # Split bundled spec into per-API JSON files (api.edit.json, api.serve.json, api.ingest.json)
 node scripts/split-by-api.cjs "$OAS3_JSON" "$DOCS_DIR"
 
+# The reference shows each request body's example; widdershins only reads them as `examples`
+SAMPLES_JSON=$(mktemp)
+node scripts/promote-request-examples.cjs "$OAS3_JSON" "$SAMPLES_JSON"
+
 # Convert OpenAPI to doc to Shins Markdown
 ./node_modules/.bin/widdershins \
     --theme vs2015 \
     --language_tabs shell:Curl http:HTTP javascript--nodejs:NodeJS php:PHP ruby:Ruby python:Python java:Java go:Go \
-    --summary "$OAS3_JSON" \
+    --summary "$SAMPLES_JSON" \
     --outfile "$DOCS_DIR/index.html.md"
+rm -f "$SAMPLES_JSON"
 
 cp "$DOCS_DIR/index.html.md" .shins/source/index.html.md
 

definitions/edit.yaml

@@ -1,46 +1,54 @@
 timeline:
-  soundtrack:
-    src: "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3"
-    effect: fadeInFadeOut
   background: "#000000"
+  fonts:
+    - src: "https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf"
   tracks:
     - clips:
         - asset:
-            type: title
+            type: rich-text
             text: Hello World
-            style: minimal
+            font:
+              family: JTUSjIg1_i6t8kCHKm45xW5rygbi49c
+              size: 64
+              weight: "700"
+              color: "#ffffff"
+            align:
+              horizontal: center
+              vertical: middle
           start: 0
           length: 4
           transition:
             in: fade
             out: fade
-          effect: slideRight
         - asset:
             type: image
-            src: >-
-              https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-image.jpg
-          start: 3
-          length: 4
+            src: "https://shotstack-assets.s3.amazonaws.com/images/earth.jpg"
+          start: 4
+          length: 3
           effect: zoomIn
           filter: greyscale
     - clips:
         - asset:
             type: video
-            src: >-
-              https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-clip-1.mp4
-            trim: 10.5
+            src: "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4"
             transcode: true
           start: 7
           length: 4.5
         - asset:
             type: video
-            src: >-
-              https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-clip-2.mp4
+            src: "https://shotstack-assets.s3.amazonaws.com/footage/city-timelapse.mp4"
             volume: 0.5
           start: 11.5
           length: 5
           transition:
             out: wipeLeft
+    - clips:
+        - asset:
+            type: audio
+            src: "https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3"
+            effect: fadeInFadeOut
+          start: 0
+          length: end
 output:
   format: mp4
-  resolution: sd
+  resolution: sd

package.json

@@ -42,7 +42,8 @@
     "start": "cross-env ./build-docs.sh && http-server build/docs/ -o -c-1",
     "deploy:docs": "aws s3 sync build/docs/ s3://shotstack.io/docs/api",
     "prepublishOnly": "node scripts/publish-guard.cjs && pnpm build && pnpm test",
-    "test:smoke": "node tests/smoke.cjs"
+    "test:smoke": "node tests/smoke.cjs",
+    "test:examples": "node tests/request-examples.cjs"
   },
   "repository": {
     "type": "git",

paths/assets.yaml

@@ -11,6 +11,11 @@ post:
       Fetch an asset from a URL and send it to one or more destinations.
     content:
       application/json:
+        example:
+          url: 'https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/music/moment.mp3'
+          id: 018e8937-5015-75ee-aab6-03f214981133
+          destinations:
+            - provider: shotstack
         schema:
           $ref: "../schemas/serve/transfer.yaml#/Transfer"
     required: true

paths/generate.yaml

@@ -94,6 +94,11 @@
           A prompt-bearing image, video or audio asset to generate.
         content:
           application/json:
+            example:
+              asset:
+                type: image
+                prompt: 'A lighthouse on a rocky coast at sunset, cinematic lighting'
+                model: nano-banana-2
             schema:
               type: object
               properties:

paths/renderid.yaml

@@ -14,7 +14,60 @@
                   url: >-
                     https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4
                   data:
-                    $ref: "../definitions/edit.yaml"
+                    timeline:
+                      background: '#000000'
+                      fonts:
+                        - src: 'https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf'
+                      tracks:
+                        - clips:
+                            - asset:
+                                type: rich-text
+                                text: Hello World
+                                font:
+                                  family: JTUSjIg1_i6t8kCHKm45xW5rygbi49c
+                                  size: 64
+                                  weight: '700'
+                                  color: '#ffffff'
+                                align:
+                                  horizontal: center
+                                  vertical: middle
+                              start: 0
+                              length: 4
+                              transition:
+                                in: fade
+                                out: fade
+                            - asset:
+                                type: image
+                                src: 'https://shotstack-assets.s3.amazonaws.com/images/earth.jpg'
+                              start: 4
+                              length: 3
+                              effect: zoomIn
+                              filter: greyscale
+                        - clips:
+                            - asset:
+                                type: video
+                                src: 'https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4'
+                                transcode: true
+                              start: 7
+                              length: 4.5
+                            - asset:
+                                type: video
+                                src: 'https://shotstack-assets.s3.amazonaws.com/footage/city-timelapse.mp4'
+                                volume: 0.5
+                              start: 11.5
+                              length: 5
+                              transition:
+                                out: wipeLeft
+                        - clips:
+                            - asset:
+                                type: audio
+                                src: 'https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3'
+                                effect: fadeInFadeOut
+                              start: 0
+                              length: end
+                    output:
+                      format: mp4
+                      resolution: sd
                   created: "2020-10-30T09:42:29.446Z"
                   updated: "2020-10-30T09:42:39.168Z"
               schema:

paths/templates.yaml

@@ -12,6 +12,35 @@
           Create a template with a name and [Edit](#tocs_edit).
         content:
           application/json:
+            example:
+              name: Jane's welcome video
+              template:
+                timeline:
+                  fonts:
+                    - src: 'https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf'
+                  tracks:
+                    - clips:
+                        - asset:
+                            type: rich-text
+                            text: 'HELLO {{NAME}}'
+                            font:
+                              family: JTUSjIg1_i6t8kCHKm45xW5rygbi49c
+                              size: 72
+                              weight: '800'
+                              color: '#ffffff'
+                            align:
+                              horizontal: center
+                              vertical: middle
+                          start: 0
+                          length: 5
+                output:
+                  format: mp4
+                  size:
+                    width: 1024
+                    height: 576
+                merge:
+                  - find: NAME
+                    replace: World
             schema:
               $ref: "../schemas/template.yaml#/Template"
         required: true

paths/templatesid.yaml

@@ -30,6 +30,35 @@
           provided. If the template parameter is omitted a blank template will be saved.
         content:
           application/json:
+            example:
+              name: Jane's welcome video
+              template:
+                timeline:
+                  fonts:
+                    - src: 'https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf'
+                  tracks:
+                    - clips:
+                        - asset:
+                            type: rich-text
+                            text: 'HELLO {{NAME}}'
+                            font:
+                              family: JTUSjIg1_i6t8kCHKm45xW5rygbi49c
+                              size: 72
+                              weight: '800'
+                              color: '#ffffff'
+                            align:
+                              horizontal: center
+                              vertical: middle
+                          start: 0
+                          length: 5
+                output:
+                  format: mp4
+                  size:
+                    width: 1024
+                    height: 576
+                merge:
+                  - find: NAME
+                    replace: World
             schema:
               $ref: "../schemas/template.yaml#/Template"
         required: true

paths/templatesrender.yaml

@@ -11,6 +11,11 @@
           Render a template by template id.
         content:
           application/json:
+            example:
+              id: f5493c17-d01f-445c-bb49-535fae65f219
+              merge:
+                - find: NAME
+                  replace: Jane
             schema:
               $ref: "../schemas/templaterender.yaml#/TemplateRender"
         required: true

schemas/imageasset.yaml

@@ -42,7 +42,7 @@
             `nano-banana-2`). Defaults to `nano-banana-2` if omitted. Each
             model's available options are defined by the model registry.
           type: string
-          example: flux-schnell
+          example: nano-banana-2
         options:
           description: >-
             Model-specific generation settings. Valid keys and values depend on

schemas/responses/templatedataresponsedata.yaml

@@ -17,7 +17,60 @@
           description: The [Edit](#tocs_edit) template.
           $ref: "../edit.yaml#/Edit"
           example:
-            $ref: "../../definitions/edit.yaml"
+            timeline:
+              background: '#000000'
+              fonts:
+                - src: 'https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf'
+              tracks:
+                - clips:
+                    - asset:
+                        type: rich-text
+                        text: Hello World
+                        font:
+                          family: JTUSjIg1_i6t8kCHKm45xW5rygbi49c
+                          size: 64
+                          weight: '700'
+                          color: '#ffffff'
+                        align:
+                          horizontal: center
+                          vertical: middle
+                      start: 0
+                      length: 4
+                      transition:
+                        in: fade
+                        out: fade
+                    - asset:
+                        type: image
+                        src: 'https://shotstack-assets.s3.amazonaws.com/images/earth.jpg'
+                      start: 4
+                      length: 3
+                      effect: zoomIn
+                      filter: greyscale
+                - clips:
+                    - asset:
+                        type: video
+                        src: 'https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4'
+                        transcode: true
+                      start: 7
+                      length: 4.5
+                    - asset:
+                        type: video
+                        src: 'https://shotstack-assets.s3.amazonaws.com/footage/city-timelapse.mp4'
+                        volume: 0.5
+                      start: 11.5
+                      length: 5
+                      transition:
+                        out: wipeLeft
+                - clips:
+                    - asset:
+                        type: audio
+                        src: 'https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3'
+                        effect: fadeInFadeOut
+                      start: 0
+                      length: end
+            output:
+              format: mp4
+              resolution: sd
       required:
         - id
         - name

scripts/promote-request-examples.cjs

@@ -0,0 +1,15 @@
+const fs = require('node:fs');
+
+// Widdershins shows only a request body's `examples`, and ignores the singular `example` the spec uses (which
+// openapi-typescript needs for its @example docs). The copy widdershins reads gets each `example` as `examples`.
+const [source, target] = process.argv.slice(2);
+const api = JSON.parse(fs.readFileSync(source, 'utf8'));
+for (const operations of Object.values(api.paths)) {
+  for (const operation of Object.values(operations)) {
+    const content = operation?.requestBody?.content?.['application/json'];
+    if (content?.example === undefined || content.examples) continue;
+    content.examples = { default: { value: content.example } };
+    delete content.example;
+  }
+}
+fs.writeFileSync(target, JSON.stringify(api));

tests/reference-code-samples.cjs

@@ -17,3 +17,31 @@ const truncated = php.filter(({ code }) => !code.startsWith('<span class="hljs-m
 assert.equal(truncated.length, 0,
   `PHP samples missing their opening lines: ${truncated.map(({ id }) => id).join(', ')}`);
 console.log(`PHP samples: ${php.length} complete`);
+
+// Widdershins marks objects it reaches through a $ref; the mark must never reach the page.
+const annotated = html.split('<h2 id="').slice(1).filter((section) => section.includes('x-widdershins-'))
+  .map((section) => section.slice(0, section.indexOf('"')));
+assert.equal(annotated.length, 0, `widdershins annotations shown in: ${annotated.join(', ')}`);
+
+// Each request body panel shows the spec's example for that body.
+const api = require(path.resolve(__dirname, '..', 'build/docs/api.bundled.json'));
+const decode = (code) => code.replace(/<[^>]+>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+  .replace(/&quot;/g, '"').replace(/&#x27;|&#39;/g, "'").replace(/&amp;/g, '&');
+const panels = html.split('<h2 id="').slice(1).flatMap((section) => {
+  const [, method, route] = section.match(/<p><code>(GET|POST|PUT|PATCH|DELETE) (\/[^<]*)<\/code><\/p>/) ?? [];
+  const operation = api.paths[route]?.[method?.toLowerCase()];
+  const example = operation?.requestBody?.content?.['application/json']?.example;
+  const panel = section.split('Body parameter')[1]?.match(/<pre class="highlight tab tab-json"><code>([\s\S]*?)<\/code><\/pre>/);
+  return example === undefined ? [] : [{ operationId: operation.operationId, example, shown: panel && decode(panel[1]) }];
+});
+const stale = panels.filter(({ example, shown }) => {
+  try {
+    assert.deepEqual(JSON.parse(shown), example);
+    return false;
+  } catch {
+    return true;
+  }
+});
+assert.ok(panels.length > 0, 'no request body panels on the page');
+assert.equal(stale.length, 0, `body panels not showing the spec's example: ${stale.map(({ operationId }) => operationId).join(', ')}`);
+console.log(`Request body panels: ${panels.length} show their example`);