feat(specs): add cURL snippets (#3841)

Author: shortcuts

scripts/package.json

@@ -25,6 +25,7 @@
     "@actions/core": "1.11.1",
     "@actions/exec": "1.1.1",
     "@actions/io": "1.1.3",
+    "@har-sdk/oas": "2.10.0",
     "@octokit/rest": "21.0.2",
     "@types/express": "5.0.0",
     "@types/folder-hash": "4.0.4",
@@ -43,6 +44,7 @@
     "express": "4.21.0",
     "folder-hash": "4.0.4",
     "fs-extra": "11.2.0",
+    "httpsnippet": "3.0.1",
     "js-yaml": "4.1.0",
     "knip": "5.30.4",
     "micromatch": "4.0.8",

scripts/specs/format.ts

@@ -1,9 +1,11 @@
 import fsp from 'fs/promises';
 
+import oas2har from '@har-sdk/oas';
+import { HarRequest, HTTPSnippet } from 'httpsnippet';
 import yaml from 'js-yaml';
 
 import { Cache } from '../cache.js';
-import { GENERATORS, exists, run, toAbsolutePath } from '../common.js';
+import { exists, GENERATORS, run, toAbsolutePath } from '../common.js';
 import { createSpinner } from '../spinners.js';
 import type { Spec } from '../types.js';
 
@@ -59,6 +61,7 @@ export async function transformBundle({
   }
 
   const bundledSpec = yaml.load(await fsp.readFile(bundledPath, 'utf8')) as Spec;
+  const harRequests = await oas2har.oas2har(bundledSpec as any, { includeVendorExamples: true });
   const tagsDefinitions = bundledSpec.tags;
   const snippetSamples = docs ? await transformSnippetsToCodeSamples(clientName) : ({} as SnippetSamples);
 
@@ -100,6 +103,33 @@ export async function transformBundle({
         }
       }
 
+      // skip custom path for cURL
+      if (pathKey !== '/{path}' && specMethod['x-codeSamples']) {
+        const harRequest = harRequests.find((baseHarRequest) =>
+          baseHarRequest.url.includes(pathKey.replace('{indexName}', 'ALGOLIA_INDEX_NAME')),
+        );
+
+        if (!harRequest?.headers) {
+          break;
+        }
+
+        for (const harRequestHeader of harRequest.headers) {
+          if (harRequestHeader.name === bundledSpec.components.securitySchemes.appId?.name) {
+            harRequestHeader.value = 'ALGOLIA_APPLICATION_ID';
+          }
+
+          if (harRequestHeader.name === bundledSpec.components.securitySchemes.apiKey?.name) {
+            harRequestHeader.value = 'ALGOLIA_API_KEY';
+          }
+        }
+
+        specMethod['x-codeSamples'].push({
+          lang: 'cURL',
+          label: 'curl',
+          source: `${new HTTPSnippet(harRequest as HarRequest).convert('shell', 'curl')}`,
+        });
+      }
+
       if (!bundledSpec.paths[pathKey][method].tags) {
         continue;
       }

scripts/types.ts

@@ -46,6 +46,7 @@ export type Spec = {
   paths: Path;
   components: {
     schemas: Record<string, any>;
+    securitySchemes: Partial<{ appId?: Record<string, any>; apiKey?: Record<string, any> }>;
   };
 };
 

specs/common/parameters.yml

@@ -6,7 +6,7 @@ IndexName:
   required: true
   schema:
     type: string
-    example: YourIndexName
+    example: ALGOLIA_INDEX_NAME
 
 ObjectID:
   name: objectID
@@ -24,7 +24,7 @@ Index:
   required: true
   schema:
     type: string
-    example: YourIndexName
+    example: ALGOLIA_INDEX_NAME
 
 StartDate:
   in: query

specs/insights/common/schemas/EventAttributes.yml

@@ -13,7 +13,7 @@ eventName:
 index:
   type: string
   description: Index name (case-sensitive) to which the event's items belong.
-  example: YourIndexName
+  example: ALGOLIA_INDEX_NAME
 
 userToken:
   type: string

specs/recommend/spec.yml

@@ -73,23 +73,23 @@ servers:
   - url: https://{appId}.algolianet.com
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
   - url: https://{appId}-1.algolianet.com
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
   - url: https://{appId}-2.algolianet.com
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
   - url: https://{appId}-3.algolianet.com
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
   - url: https://{appId}-dsn.algolianet.com
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
 security:
   - appId: []
     apiKey: []

specs/search/paths/keys/common/parameters.yml

@@ -4,5 +4,5 @@ KeyString:
   required: true
   schema:
     type: string
-    example: YourAPIKey
+    example: ALGOLIA_API_KEY
   description: API key.

specs/search/spec.yml

@@ -89,23 +89,23 @@ servers:
   - url: https://{appId}.algolia.net
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
   - url: https://{appId}-1.algolianet.com
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
   - url: https://{appId}-2.algolianet.com
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
   - url: https://{appId}-3.algolianet.com
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
   - url: https://{appId}-dsn.algolia.net
     variables:
       appId:
-        default: myAppId
+        default: ALGOLIA_APPLICATION_ID
 security:
   - appId: []
     apiKey: []