[swagger.js] Add option includeOperations to toJSONAsync() (Azure#38693)

- Useful for testing "get operations" on all specs in repo

Author: mikeharder

.github/shared/cmd/spec-model.js

@@ -4,15 +4,20 @@ import { debugLogger } from "../src/logger.js";
 import { SpecModel } from "../src/spec-model.js";
 
 const USAGE =
-  "Usage: npx spec-model path/to/spec [--debug] [--include-refs] [--relative-paths] [--no-embed-errors]\n" +
-  "Example: npx spec-model specification/widget";
+  "Usage: npx spec-model path/to/spec [--debug] [--include-operations] [--include-refs] [--relative-paths] [--no-embed-errors]\n" +
+  "Examples:\n" +
+  "  npx spec-model specification/widget\n" +
+  "  npx spec-model specification --include-operations --include-refs > out.txt; grep out.txt '\"error\":'";
 
 // Exclude first two args (node, script file)
 let args = process.argv.slice(2);
 
 const debug = args.includes("--debug");
 args = args.filter((a) => a != "--debug");
 
+const includeOperations = args.includes("--include-operations");
+args = args.filter((a) => a != "--include-operations");
+
 const includeRefs = args.includes("--include-refs");
 args = args.filter((a) => a != "--include-refs");
 
@@ -42,7 +47,12 @@ const specModel = new SpecModel(specPath, { logger });
 
 console.log(
   JSON.stringify(
-    await specModel.toJSONAsync({ embedErrors: !noEmbedErrors, includeRefs, relativePaths }),
+    await specModel.toJSONAsync({
+      embedErrors: !noEmbedErrors,
+      includeOperations,
+      includeRefs,
+      relativePaths,
+    }),
     null,
     2,
   ),

.github/shared/src/spec-model.js

@@ -26,6 +26,7 @@ import { SpecModelError } from "./spec-model-error.js";
 /**
  * @typedef {Object} ToJSONOptions
  * @prop {boolean} [embedErrors]
+ * @prop {boolean} [includeOperations] Whether to include the operations in each swagger. Increases runtime about 20x, from 6s to 120s for whole specs repo.
  * @prop {boolean} [includeRefs]
  * @prop {boolean} [relativePaths]
  */

.github/shared/src/swagger.js

@@ -24,6 +24,7 @@ import { embedError } from "./spec-model.js";
 /**
  * @typedef {Object} SwaggerJSON
  * @property {string} path
+ * @property {Operation[]} [operations]
  * @property {Object[]} [refs]
  */
 
@@ -292,14 +293,20 @@ export class Swagger {
    * @returns {Promise<SwaggerJSON|ErrorJSON>}
    */
   async toJSONAsync(options = {}) {
-    const { includeRefs, relativePaths } = options;
+    const { includeOperations, includeRefs, relativePaths } = options;
 
     return await embedError(
       async () => ({
         path:
           relativePaths && this.#tag?.readme?.specModel
             ? relative(this.#tag?.readme?.specModel.folder, this.#path)
             : this.#path,
+        operations: includeOperations
+          ? [...(await this.getOperations()).values()].map((o) => {
+              // Create new object with properties in preferred output order
+              return { path: o.path, httpMethod: o.httpMethod, id: o.id };
+            })
+          : undefined,
         refs: includeRefs
           ? await mapAsync(
               [...(await this.getRefs()).values()].sort((a, b) => a.path.localeCompare(b.path)),

.github/shared/test/spec-model.test.js

@@ -109,13 +109,18 @@ describe("SpecModel", () => {
 
     const jsonRefsRelative = /** @type {SpecModelJSON} */ (
       await specModel.toJSONAsync({
+        includeOperations: true,
         includeRefs: true,
         relativePaths: true,
       })
     );
     const readmeJSONRelative = /** @type {ReadmeJSON} */ (jsonRefsRelative.readmes[0]);
     const readmePathRelative = readmeJSONRelative.path;
     expect(isAbsolute(readmePathRelative)).toBe(false);
+    expect(
+      /** @type {SwaggerJSON}*/ (/** @type {TagJSON} */ (readmeJSONRelative.tags[0]).inputFiles[0])
+        .operations,
+    ).toBeDefined();
     expect(
       /** @type {SwaggerJSON}*/ (/** @type {TagJSON} */ (readmeJSONRelative.tags[0]).inputFiles[0])
         .refs,