Add support for converting OpenAPI3 specs to TypeSpec

.chronus/changes/oa3-to-ts-2024-5-26-13-27-36.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Adds support for converting OpenAPI3 specs to TypeSpec via the new openapi3-to-tsp CLI included in the @typespec/openapi3 package.

docs/emitters/openapi3/reference/index.mdx

@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 
 # Overview
 
-TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding
+TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec
 
 ## Install
 

packages/openapi3/README.md

@@ -1,6 +1,6 @@
 # @typespec/openapi3
 
-TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding
+TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec
 
 ## Install
 

packages/openapi3/cmd/tsp-openapi3.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from "../dist/src/cli/cli.js";
+
+main().catch((error) => {
+  // eslint-disable-next-line no-console
+  console.error(error);
+
+  process.exit(1);
+});

packages/openapi3/package.json

@@ -2,7 +2,7 @@
   "name": "@typespec/openapi3",
   "version": "0.57.0",
   "author": "Microsoft Corporation",
-  "description": "TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding",
+  "description": "TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec",
   "homepage": "https://typespec.io",
   "readme": "https://github.com/microsoft/typespec/blob/main/README.md",
   "license": "MIT",
@@ -16,6 +16,9 @@
   "keywords": [
     "typespec"
   ],
+  "bin": {
+    "tsp-openapi3": "cmd/tsp-openapi3.js"
+  },
   "type": "module",
   "main": "dist/src/index.js",
   "tspMain": "lib/main.tsp",
@@ -34,7 +37,7 @@
   },
   "scripts": {
     "clean": "rimraf ./dist ./temp",
-    "build": "npm run gen-extern-signature && tsc -p . && npm run lint-typespec-library",
+    "build": "npm run gen-version && npm run gen-extern-signature && tsc -p . && npm run lint-typespec-library",
     "watch": "tsc -p . --watch",
     "gen-extern-signature": "tspd --enable-experimental gen-extern-signature .",
     "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
@@ -44,15 +47,20 @@
     "test:ci": "vitest run --coverage --reporter=junit --reporter=default",
     "lint": "eslint . --max-warnings=0",
     "lint:fix": "eslint . --fix",
-    "regen-docs": "tspd doc .  --enable-experimental  --output-dir ../../docs/emitters/openapi3/reference"
+    "regen-docs": "tspd doc .  --enable-experimental  --output-dir ../../docs/emitters/openapi3/reference",
+    "regen-specs": "cross-env RECORD=true vitest run",
+    "gen-version": "node scripts/generate-version.js"
   },
   "files": [
     "lib/*.tsp",
     "dist/**",
     "!dist/test/**"
   ],
   "dependencies": {
-    "yaml": "~2.4.5"
+    "@readme/openapi-parser": "~2.6.0",
+    "@typespec/prettier-plugin-typespec": "workspace:~",
+    "yaml": "~2.4.5",
+    "yargs": "~17.7.2"
   },
   "peerDependencies": {
     "@typespec/compiler": "workspace:~",
@@ -62,6 +70,7 @@
   },
   "devDependencies": {
     "@types/node": "~18.11.19",
+    "@types/yargs": "~17.0.32",
     "@typespec/compiler": "workspace:~",
     "@typespec/http": "workspace:~",
     "@typespec/library-linter": "workspace:~",
@@ -72,7 +81,9 @@
     "@vitest/coverage-v8": "^1.6.0",
     "@vitest/ui": "^1.6.0",
     "c8": "^10.1.2",
+    "cross-env": "~7.0.3",
     "rimraf": "~5.0.7",
+    "ts-node": "~10.9.2",
     "typescript": "~5.5.3",
     "vitest": "^1.6.0"
   }

packages/openapi3/scripts/generate-version.js

@@ -0,0 +1,27 @@
+// @ts-check
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+const root = fileURLToPath(new URL("..", import.meta.url).href);
+const distDir = join(root, "dist");
+const versionTarget = join(distDir, "version.js");
+
+function loadPackageJson() {
+  const packageJsonPath = join(root, "package.json");
+  return JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+}
+
+function main() {
+  const pkg = loadPackageJson();
+
+  const version = pkg.version;
+
+  if (!existsSync(distDir)) {
+    mkdirSync(distDir, { recursive: true });
+  }
+
+  const versionJs = `export const version = "${version}";`;
+  writeFileSync(versionTarget, versionJs);
+}
+
+main();

packages/openapi3/src/cli/actions/convert/args.ts

@@ -0,0 +1,4 @@
+export interface ConvertCliArgs {
+  "output-dir"?: string;
+  args?: string[];
+}

packages/openapi3/src/cli/actions/convert/convert.ts

@@ -0,0 +1,30 @@
+import oaParser from "@readme/openapi-parser";
+import { resolvePath } from "@typespec/compiler";
+import { OpenAPI3Document } from "../../../types.js";
+import { CliHost } from "../../types.js";
+import { handleInternalCompilerError } from "../../utils.js";
+import { ConvertCliArgs } from "./args.js";
+import { generateMain } from "./generators/generate-main.js";
+import { transform } from "./transforms/transforms.js";
+
+export async function convertAction(host: CliHost, args: ConvertCliArgs & { path: string }) {
+  // attempt to read the file
+  const fullPath = resolvePath(process.cwd(), args.path);
+  const model = await parseOpenApiFile(fullPath);
+  const program = transform(model);
+  let mainTsp: string;
+  try {
+    mainTsp = await generateMain(program);
+  } catch (err) {
+    handleInternalCompilerError(err);
+  }
+
+  if (args["output-dir"]) {
+    await host.mkdirp(args["output-dir"]);
+    await host.writeFile(resolvePath(args["output-dir"], "main.tsp"), mainTsp);
+  }
+}
+
+function parseOpenApiFile(path: string): Promise<OpenAPI3Document> {
+  return oaParser.bundle(path) as Promise<OpenAPI3Document>;
+}

packages/openapi3/src/cli/actions/convert/generators/generate-decorators.ts

@@ -0,0 +1,13 @@
+import { TypeSpecDecorator } from "../interfaces.js";
+
+function generateDecorator({ name, args }: TypeSpecDecorator): string {
+  const hasArgs = args.length;
+  const stringifiedArguments = hasArgs ? `(${args.map((a) => JSON.stringify(a)).join(", ")})` : "";
+
+  return `@${name}${stringifiedArguments}`;
+}
+
+export function generateDecorators(decorators: TypeSpecDecorator[]): string[] {
+  const uniqueDecorators = new Set<string>(decorators.map(generateDecorator));
+  return Array.from(uniqueDecorators);
+}

packages/openapi3/src/cli/actions/convert/generators/generate-main.ts

@@ -0,0 +1,27 @@
+import { formatTypeSpec } from "@typespec/compiler";
+import { TypeSpecProgram } from "../interfaces.js";
+import { generateModel } from "./generate-model.js";
+import { generateOperation } from "./generate-operation.js";
+import { generateServiceInformation } from "./generate-service-info.js";
+
+export async function generateMain(program: TypeSpecProgram): Promise<string> {
+  const content = `
+  import "@typespec/http";
+  import "@typespec/openapi";
+  import "@typespec/openapi3";
+
+  using Http;
+  using OpenAPI;
+
+  ${generateServiceInformation(program.serviceInfo)}
+
+  ${program.models.map(generateModel).join("\n\n")}
+
+  ${program.operations.map(generateOperation).join("\n\n")}
+  `;
+
+  return formatTypeSpec(content, {
+    printWidth: 100,
+    tabWidth: 2,
+  });
+}

packages/openapi3/src/cli/actions/convert/generators/generate-model.ts

@@ -0,0 +1,69 @@
+import { TypeSpecModel, TypeSpecModelProperty } from "../interfaces.js";
+import { getDecoratorsForSchema } from "../utils/decorators.js";
+import { generateDocs } from "../utils/docs.js";
+import { generateDecorators } from "./generate-decorators.js";
+import { generateTypeFromSchema } from "./generate-types.js";
+
+export function generateModel(model: TypeSpecModel): string {
+  const definitions: string[] = [];
+  const modelDeclaration = generateModelDeclaration(model);
+
+  if (model.doc) {
+    definitions.push(generateDocs(model.doc));
+  }
+
+  definitions.push(...generateDecorators(model.decorators));
+  definitions.push(modelDeclaration.open);
+
+  definitions.push(...model.properties.map(generateModelProperty));
+
+  if (model.additionalProperties) {
+    definitions.push(`...${generateTypeFromSchema(model.additionalProperties)};`);
+  }
+
+  if (modelDeclaration.close) definitions.push(modelDeclaration.close);
+
+  return definitions.join("\n");
+}
+
+type ModelDeclarationOutput = { open: string; close?: string };
+
+function generateModelDeclaration(model: TypeSpecModel): ModelDeclarationOutput {
+  const modelName = model.name;
+  const modelType = model.type ?? "object";
+
+  if (model.is) {
+    return { open: `model ${modelName} is ${model.is};` };
+  }
+
+  if (!model.extends) {
+    return { open: `model ${modelName} {`, close: "}" };
+  }
+
+  if (modelType === "object") {
+    return { open: `model ${modelName} extends ${model.extends} {`, close: "}" };
+  }
+
+  switch (modelType) {
+    case "boolean":
+    case "integer":
+    case "number":
+    case "string":
+      return { open: `scalar ${modelName} extends ${model.extends};` };
+  }
+
+  return { open: `model ${modelName} {`, close: "}" };
+}
+
+function generateModelProperty(property: TypeSpecModelProperty): string {
+  // Decorators will be a combination of top-level (parameters) and
+  // schema-level decorators.
+  const decorators = generateDecorators([
+    ...property.decorators,
+    ...getDecoratorsForSchema(property.schema),
+  ]).join(" ");
+
+  const doc = property.doc ? generateDocs(property.doc) : "";
+
+  return `${doc}${decorators} ${property.name}${property.isOptional ? "?" : ""}: ${generateTypeFromSchema(property.schema)};`;
+}