Refactor, add parameters for V2 (#448)

* Combine schemas

* Add more items to components object

* Fix comment linebreak bug

* Make content more consistent

Author: drwpow

.eslintrc.js

@@ -7,6 +7,7 @@ module.exports = {
     "@typescript-eslint/explicit-module-boundary-types": "off",
     "@typescript-eslint/no-explicit-any": "off", // in a foreign schema, sometimes we need “any”
     "@typescript-eslint/no-use-before-define": "off",
+    "@typescript-eslint/no-var-requires": "off",
     "prettier/prettier": "error",
     "prefer-const": "off",
   },

README.md

@@ -41,7 +41,31 @@ npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output pets
 # 🚀 https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]
 ```
 
-_Thanks to @psmyrdek for this feature!_
+_Thanks to @psmyrdek for the remote spec feature!_
+
+#### Using in TypeScript
+
+Import any top-level item from the generated spec to use it. It works best if you also alias types to save on typing:
+
+```ts
+import { components } from './generated-schema.ts';
+
+type APIResponse = components["schemas"]["APIResponse"];
+```
+
+The reason for all the `["…"]` everywhere is because OpenAPI lets you use more characters than are valid TypeScript identifiers. The goal of this project is to generate _all_ of your schema, not merely the parts that are “TypeScript-safe.”
+
+Also note that there’s a special `operations` interface that you can import `OperationObjects` by their [operationId][openapi-operationid]:
+
+```ts
+import { operations } from './generated-schema.ts';
+
+type getUsersById = operations["getUsersById"];
+```
+
+This is the only place where our generation differs from your schema as-written, but it’s done so as a convenience and shouldn’t cause any issues (you can still use deep references as-needed).
+
+_Thanks to @gr2m for the operations feature!_
 
 #### Outputting to `stdout`
 
@@ -86,6 +110,7 @@ For anything more complicated, or for generating specs dynamically, you can also
 | :----------------------------- | :---- | :------: | :--------------------------------------------------------------- |
 | `--output [location]`          | `-o`  | (stdout) | Where should the output file be saved?                           |
 | `--prettier-config [location]` |       |          | (optional) Path to your custom Prettier configuration for output |
+| `--raw-schema`                 |       | `false`  | Generate TS types from partial schema (e.g. having `components.schema` at the top level) |
 
 ### Node
 
@@ -108,35 +133,6 @@ post-process, and save the output anywhere.
 If your specs are in YAML, you’ll have to convert them to JS objects using a library such as [js-yaml][js-yaml]. If
 you’re batching large folders of specs, [glob][glob] may also come in handy.
 
-#### PropertyMapper
-
-In order to allow more control over how properties are parsed, and to specifically handle `x-something`-properties, the
-`propertyMapper` option may be specified as the optional 2nd parameter.
-
-This is a function that, if specified, is called for each property and allows you to change how openapi-typescript
-handles parsing of Swagger files.
-
-An example on how to use the `x-nullable` property to control if a property is optional:
-
-```js
-const getNullable = (d: { [key: string]: any }): boolean => {
-  const nullable = d["x-nullable"];
-  if (typeof nullable === "boolean") {
-    return nullable;
-  }
-  return true;
-};
-
-const output = swaggerToTS(swagger, {
-  propertyMapper: (swaggerDefinition, property): Property => ({
-    ...property,
-    optional: getNullable(swaggerDefinition),
-  }),
-});
-```
-
-_Thanks to @atlefren for this feature!_
-
 ## Migrating from v1 to v2
 
 [Migrating from v1 to v2](./docs/migrating-from-v1.md)
@@ -156,9 +152,10 @@ encouraged but not required.
 
 [glob]: https://www.npmjs.com/package/glob
 [js-yaml]: https://www.npmjs.com/package/js-yaml
-[openapi2]: https://swagger.io/specification/v2/
 [namespace]: https://www.typescriptlang.org/docs/handbook/namespaces.html
 [npm-run-all]: https://www.npmjs.com/package/npm-run-all
+[openapi-operationid]: https://swagger.io/specification/#operation-object
+[openapi2]: https://swagger.io/specification/v2/
 [openapi3]: https://swagger.io/specification
 [prettier]: https://npmjs.com/prettier
 

examples/stripe-openapi2.ts

@@ -1,9 +1,9 @@
 import path from "path";
 import prettier from "prettier";
 import { swaggerVersion } from "./utils";
-import { OpenAPI2, OpenAPI2Schemas, OpenAPI3, OpenAPI3Schemas, SwaggerToTSOptions } from "./types";
-import v2 from "./v2";
-import v3 from "./v3";
+import { transformAll } from "./transform/index";
+import { OpenAPI2, OpenAPI3, SchemaObject, SwaggerToTSOptions } from "./types/index";
+export * from "./types/index";
 
 export const WARNING_MESSAGE = `/**
 * This file was auto-generated by openapi-typescript.
@@ -14,24 +14,18 @@ export const WARNING_MESSAGE = `/**
 `;
 
 export default function swaggerToTS(
-  schema: OpenAPI2 | OpenAPI2Schemas | OpenAPI3 | OpenAPI3Schemas,
+  schema: OpenAPI2 | OpenAPI3 | Record<string, SchemaObject>,
   options?: SwaggerToTSOptions
 ): string {
-  // generate types for V2 and V3
+  // 1. determine version
   const version = (options && options.version) || swaggerVersion(schema as OpenAPI2 | OpenAPI3);
-  let output = `${WARNING_MESSAGE}`;
-  switch (version) {
-    case 2: {
-      output = output.concat(v2(schema as OpenAPI2 | OpenAPI2Schemas, options));
-      break;
-    }
-    case 3: {
-      output = output.concat(v3(schema as OpenAPI3 | OpenAPI3Schemas, options));
-      break;
-    }
-  }
 
-  // Prettify output
+  // 2. generate output
+  let output = `${WARNING_MESSAGE}
+  ${transformAll(schema, { version, rawSchema: options && options.rawSchema })}
+`;
+
+  // 3. Prettify output
   let prettierOptions: prettier.Options = { parser: "typescript" };
   if (options && options.prettierConfig) {
     try {

examples/stripe-openapi3.ts

@@ -0,0 +1,17 @@
+import { comment } from "../utils";
+import { HeaderObject } from "../types";
+import { transformSchemaObj } from "./schema";
+
+export function transformHeaderObjMap(headerMap: Record<string, HeaderObject>): string {
+  let output = "";
+
+  Object.entries(headerMap).forEach(([k, v]) => {
+    if (!v.schema) return;
+
+    if (v.description) output += comment(v.description);
+    const required = v.required ? "" : "?";
+    output += `  "${k}"${required}: ${transformSchemaObj(v.schema)}\n`;
+  });
+
+  return output;
+}

package-lock.json

@@ -0,0 +1,122 @@
+import { OperationObject } from "../types";
+import { comment } from "../utils";
+import { transformHeaderObjMap } from "./headers";
+import { transformOperationObj } from "./operation";
+import { transformPathsObj } from "./paths";
+import { transformResponsesObj } from "./responses";
+import { transformSchemaObjMap } from "./schema";
+
+interface TransformOptions {
+  rawSchema?: boolean;
+  version: number;
+}
+
+export function transformAll(schema: any, { version, rawSchema }: TransformOptions): string {
+  let output = "";
+
+  let operations: Record<string, OperationObject> = {};
+
+  // --raw-schema mode
+  if (rawSchema) {
+    switch (version) {
+      case 2: {
+        return `export interface definitions {\n  ${transformSchemaObjMap(schema, {
+          required: Object.keys(schema),
+        })}\n}`;
+      }
+      case 3: {
+        return `export interface schemas {\n    ${transformSchemaObjMap(schema, {
+          required: Object.keys(schema),
+        })}\n  }\n\n`;
+      }
+    }
+  }
+
+  // #/paths (V2 & V3)
+  output += `export interface paths {\n`; // open paths
+  if (schema.paths) {
+    output += transformPathsObj(schema.paths, {
+      operations,
+      parameters: (schema.components && schema.components.parameters) || schema.parameters,
+    });
+  }
+  output += `}\n\n`; // close paths
+
+  switch (version) {
+    case 2: {
+      // #/definitions
+      output += `export interface definitions {\n  ${transformSchemaObjMap(schema.definitions || {}, {
+        required: Object.keys(schema.definitions),
+      })}\n}\n\n`;
+
+      // #/parameters
+      if (schema.parameters) {
+        const required = Object.keys(schema.parameters);
+        output += `export interface parameters {\n    ${transformSchemaObjMap(schema.parameters, {
+          required,
+        })}\n  }\n\n`;
+      }
+
+      // #/parameters
+      if (schema.responses) {
+        output += `export interface responses {\n    ${transformResponsesObj(schema.responses)}\n  }\n\n`;
+      }
+      break;
+    }
+    case 3: {
+      // #/components
+      output += `export interface components {\n`; // open components
+
+      if (schema.components) {
+        // #/components/schemas
+        if (schema.components.schemas) {
+          const required = Object.keys(schema.components.schemas);
+          output += `  schemas: {\n    ${transformSchemaObjMap(schema.components.schemas, { required })}\n  }\n`;
+        }
+
+        // #/components/responses
+        if (schema.components.responses) {
+          output += `  responses: {\n    ${transformResponsesObj(schema.components.responses)}\n  }\n`;
+        }
+
+        // #/components/parameters
+        if (schema.components.parameters) {
+          const required = Object.keys(schema.components.parameters);
+          output += `  parameters: {\n    ${transformSchemaObjMap(schema.components.parameters, {
+            required,
+          })}\n  }\n`;
+        }
+
+        // #/components/requestBodies
+        if (schema.components.requestBodies) {
+          const required = Object.keys(schema.components.requestBodies);
+          output += `  requestBodies: {\n    ${transformSchemaObjMap(schema.components.requestBodies, {
+            required,
+          })}\n  }\n`;
+        }
+
+        // #/components/headers
+        if (schema.components.headers) {
+          output += `  headers: {\n    ${transformHeaderObjMap(schema.components.headers)}  }\n`;
+        }
+      }
+
+      output += `}\n\n`; // close components
+      break;
+    }
+  }
+
+  output += `export interface operations {\n`; // open operations
+  if (Object.keys(operations).length) {
+    Object.entries(operations).forEach(([operationId, operation]) => {
+      if (operation.description) output += comment(operation.description); // handle comment
+      output += `  "${operationId}": {\n    ${transformOperationObj(
+        operation,
+        schema.components && schema.components.parameters
+      )};\n  }\n`;
+    });
+  }
+  output += `}\n`; // close operations
+
+  return output.trim();
+}