feat(flags): add flag to force never response body (#905)

The OpenAPI specs state that in order to describe an Empty Response Body, the response `content` section should be omitted.
https://swagger.io/docs/specification/describing-responses/

The current behavior generates the expected `never` type for a handful of status code which should always return an empty response body.
However, when an app returns an empty response body for a status code outside of this short list, we lose type safety.

This flag allows developers to generate types with the `never` type used for every response with no `content`

Author: duncanbeevers

bin/cli.js

@@ -21,6 +21,7 @@ Options
   --header, -x                 (optional) Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the key: value pattern
   --httpMethod, -m             (optional) Provide the HTTP Verb/Method for fetching a schema from a remote URL
   --immutable-types, -it       (optional) Generates immutable types (readonly properties and readonly array)
+  --content-never              (optional) If supplied, an omitted reponse \`content\` property will be generated as \`never\` instead of \`unknown\`
   --additional-properties, -ap (optional) Allow arbitrary properties for all schema objects without "additionalProperties: false"
   --default-non-nullable       (optional) If a schema object has a default value set, don’t mark it as nullable
   --prettier-config, -c        (optional) specify path to Prettier config file
@@ -45,7 +46,7 @@ function errorAndExit(errorMessage) {
 const [, , input, ...args] = process.argv;
 const flags = parser(args, {
   array: ["header"],
-  boolean: ["defaultNonNullable", "immutableTypes", "rawSchema", "exportType", "supportArrayLength", "makePathsEnum", "pathParamsAsTypes"],
+  boolean: ["defaultNonNullable", "immutableTypes", "contentNever", "rawSchema", "exportType", "supportArrayLength", "makePathsEnum", "pathParamsAsTypes"],
   number: ["version"],
   string: ["auth", "header", "headersObject", "httpMethod", "prettierConfig"],
   alias: {
@@ -92,6 +93,7 @@ async function generateSchema(pathToSpec) {
     prettierConfig: flags.prettierConfig,
     rawSchema: flags.rawSchema,
     makePathsEnum: flags.makePathsEnum,
+    contentNever: flags.contentNever,
     silent: output === OUTPUT_STDOUT,
     version: flags.version,
     httpHeaders,

src/index.ts

@@ -43,6 +43,7 @@ async function openapiTS(
     defaultNonNullable: options.defaultNonNullable || false,
     formatter: options && typeof options.formatter === "function" ? options.formatter : undefined,
     immutableTypes: options.immutableTypes || false,
+    contentNever: options.contentNever || false,
     makePathsEnum: options.makePathsEnum || false,
     pathParamsAsTypes: options.pathParamsAsTypes,
     rawSchema: options.rawSchema || false,

src/transform/responses.ts

@@ -3,10 +3,15 @@ import { comment, tsReadonly } from "../utils.js";
 import { transformHeaderObjMap } from "./headers.js";
 import { transformSchemaObj } from "./schema.js";
 
-const resType = (res: string | number) => (res === 204 || (res >= 300 && res < 400) ? "never" : "unknown");
-
 export function transformResponsesObj(responsesObj: Record<string, any>, ctx: GlobalContext): string {
   const readonly = tsReadonly(ctx.immutableTypes);
+  const resType = (res: string | number) => {
+    if (tsReadonly(ctx.contentNever)) {
+      return "never";
+    } else {
+      return res === 204 || (res >= 300 && res < 400) ? "never" : "unknown";
+    }
+  };
 
   let output = "";
 

src/types.ts

@@ -126,6 +126,8 @@ export interface SwaggerToTSOptions {
   formatter?: SchemaFormatter;
   /** Generates immutable types (readonly properties and readonly array) */
   immutableTypes?: boolean;
+  /** (optional) If supplied, an omitted reponse \`content\` property will be generated as \`never\` instead of \`unknown\` */
+  contentNever?: boolean;
   /** (optional) Treat schema objects with default values as non-nullable */
   defaultNonNullable?: boolean;
   /** (optional) Path to Prettier config */
@@ -180,6 +182,7 @@ export interface GlobalContext {
   defaultNonNullable: boolean;
   formatter?: SchemaFormatter;
   immutableTypes: boolean;
+  contentNever: boolean;
   makePathsEnum: boolean;
   namespace?: string;
   pathParamsAsTypes?: boolean;

test/bin/cli.test.js

@@ -89,4 +89,14 @@ describe("cli", () => {
     const expected = eol.lf(fs.readFileSync(new URL("./expected/paths-enum.ts", cwd), "utf8"));
     expect(generated).to.equal(expected);
   });
+
+  it('generates the `never` type for omitted response `content` with --content-never', () => {
+    const generatedPath = "generated/content-never.ts"
+    execSync(`${cmd} specs/no-response.yaml -o ${generatedPath} --content-never`, {
+      cwd,
+    });
+    const generated = fs.readFileSync(new URL(`./${generatedPath}`, cwd), "utf8");
+    const expected = eol.lf(fs.readFileSync(new URL("./expected/content-never.ts", cwd), "utf8"));
+    expect(generated).to.equal(expected);
+  });
 });

test/bin/expected/content-never.ts

@@ -0,0 +1,21 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+  "/test": {
+    get: {
+      responses: {
+        /** OK */
+        200: never;
+      };
+    };
+  };
+}
+
+export interface components {}
+
+export interface operations {}
+
+export interface external {}

test/bin/expected/no-response.ts

@@ -0,0 +1,21 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+  "/test": {
+    get: {
+      responses: {
+        /** OK */
+        200: never;
+      };
+    };
+  };
+}
+
+export interface components {}
+
+export interface operations {}
+
+export interface external {}

test/bin/specs/no-response.yaml

@@ -0,0 +1,7 @@
+openapi: 3.0
+paths:
+  /test:
+    get:
+      responses:
+        200:
+          description: OK