fix: elide empty descriptions when allowed by the spec

The description field in responses appears to be required. Is there a reasonable default we can use for these? Perhaps the http status name?
BitGo · Aug 25, 2022 · 399f3c6 · 399f3c6
1 parent 796d7fe
commit 399f3c6
Show file tree

Hide file tree

Showing 15 changed files with 59 additions and 76 deletions.
diff --git a/packages/openapi-generator/corpus/test-array-property.ts b/packages/openapi-generator/corpus/test-array-property.ts
@@ -33,7 +33,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/corpus/test-boolean-literal.ts b/packages/openapi-generator/corpus/test-boolean-literal.ts
@@ -33,7 +33,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/corpus/test-discriminated-union.ts b/packages/openapi-generator/corpus/test-discriminated-union.ts
@@ -36,7 +36,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/corpus/test-intersection-flattening.ts b/packages/openapi-generator/corpus/test-intersection-flattening.ts
@@ -33,7 +33,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/corpus/test-multi-route.ts b/packages/openapi-generator/corpus/test-multi-route.ts
@@ -68,7 +68,6 @@ export const Routes = h.apiSpec({
     "/test/{id}/first": {
       "get": {
         "summary": "FirstRoute",
-        "description": "",
         "parameters": [
           {
             "name": "horse",
@@ -115,7 +114,6 @@ export const Routes = h.apiSpec({
     "/test/{id}/second": {
       "get": {
         "summary": "SecondRoute",
-        "description": "",
         "parameters": [
           {
             "name": "horse",

diff --git a/packages/openapi-generator/corpus/test-multi-union.ts b/packages/openapi-generator/corpus/test-multi-union.ts
@@ -33,7 +33,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/corpus/test-null-param.ts b/packages/openapi-generator/corpus/test-null-param.ts
@@ -33,7 +33,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/corpus/test-optional-property.ts b/packages/openapi-generator/corpus/test-optional-property.ts
@@ -38,11 +38,9 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [
           {
             "name": "req",
-            "description": "",
             "schema": {
               "type": "string"
             },
@@ -51,7 +49,6 @@ export const Routes = h.apiSpec({
           },
           {
             "name": "opt",
-            "description": "",
             "schema": {
               "type": "string"
             },

diff --git a/packages/openapi-generator/corpus/test-record-type.ts b/packages/openapi-generator/corpus/test-record-type.ts
@@ -33,7 +33,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/corpus/test-single-route-multi-method.ts b/packages/openapi-generator/corpus/test-single-route-multi-method.ts
@@ -59,7 +59,6 @@ export const Routes = h.apiSpec({
     "/test/{id}": {
       "get": {
         "summary": "FirstRoute",
-        "description": "",
         "parameters": [
           {
             "name": "id",
@@ -86,7 +85,6 @@ export const Routes = h.apiSpec({
       },
       "post": {
         "summary": "SecondRoute",
-        "description": "",
         "parameters": [
           {
             "name": "id",

diff --git a/packages/openapi-generator/corpus/test-string-union.ts b/packages/openapi-generator/corpus/test-string-union.ts
@@ -33,7 +33,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/corpus/test-unknown-property.ts b/packages/openapi-generator/corpus/test-unknown-property.ts
@@ -40,7 +40,6 @@ export const Routes = h.apiSpec({
     "/test/{id}": {
       "post": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [
           {
             "name": "id",

diff --git a/packages/openapi-generator/corpus/test-version-tag.ts b/packages/openapi-generator/corpus/test-version-tag.ts
@@ -38,7 +38,6 @@ export const Routes = h.apiSpec({
     "/test": {
       "get": {
         "summary": "MyRoute",
-        "description": "",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/openapi-generator/src/project.ts b/packages/openapi-generator/src/project.ts
@@ -1,4 +1,4 @@
-import { flow, pipe } from 'fp-ts/function';
+import { pipe } from 'fp-ts/function';
 import * as A from 'fp-ts/Alt';
 import * as RA from 'fp-ts/ReadonlyArray';
 import * as E from 'fp-ts/Either';
@@ -55,65 +55,63 @@ const routesForSymbol =
       variableDeclarationOfSymbol(sym),
       E.chain(schemaForApiSpec(memo)),
       E.map(
-        flow(
-          RA.reduce(
-            {},
-            (
-              paths: PathSpec,
-              {
-                path,
-                method,
-                query,
-                params,
-                body,
-                responses,
-                summary,
-                description,
-                isPrivate,
-              },
-            ) =>
-              isPrivate && !includeInternal
-                ? paths
-                : {
-                    ...paths,
-                    [path]: {
-                      ...paths[path],
-                      [method]: {
-                        summary,
-                        description,
-                        ...(isPrivate ? { 'x-internal': true } : {}),
-                        parameters: [
-                          ...(query as ParameterList),
-                          ...(params as ParameterList),
-                        ],
-                        responses: responses.reduce<OpenAPIV3_1.ResponsesObject>(
-                          (acc, { code, schema: { schema } }) => ({
-                            ...acc,
-                            [code]: {
-                              description: '',
-                              content: {
-                                'application/json': { schema },
-                              },
+        RA.reduce(
+          {},
+          (
+            paths: PathSpec,
+            {
+              path,
+              method,
+              query,
+              params,
+              body,
+              responses,
+              summary,
+              description,
+              isPrivate,
+            },
+          ) =>
+            isPrivate && !includeInternal
+              ? paths
+              : {
+                  ...paths,
+                  [path]: {
+                    ...paths[path],
+                    [method]: {
+                      summary,
+                      ...(description !== undefined ? { description } : {}),
+                      ...(isPrivate ? { 'x-internal': true } : {}),
+                      parameters: [
+                        ...(query as ParameterList),
+                        ...(params as ParameterList),
+                      ],
+                      responses: responses.reduce<OpenAPIV3_1.ResponsesObject>(
+                        (acc, { code, schema: { schema } }) => ({
+                          ...acc,
+                          [code]: {
+                            description: '', // DISCUSS: This field actually is required, is there a better default for this?
+                            content: {
+                              'application/json': { schema },
                             },
-                          }),
-                          {},
-                        ),
-                        ...(body !== undefined
-                          ? {
-                              requestBody: {
-                                content: {
-                                  'application/json': {
-                                    schema: body.schema,
-                                  },
+                          },
+                        }),
+                        {},
+                      ),
+                      ...(body !== undefined
+                        ? {
+                            requestBody: {
+                              content: {
+                                'application/json': {
+                                  schema: body.schema,
                                 },
-                                required: body.required,
                               },
-                            }
-                          : {}),
-                      },
+                              required: body.required,
+                            },
+                          }
+                        : {}),
                     },
                   },
-          ),
+                },
         ),
       ),
     );

diff --git a/packages/openapi-generator/src/route.ts b/packages/openapi-generator/src/route.ts
@@ -101,7 +101,9 @@ const parametersFromCodecOutputSym = (paramIn: 'query' | 'path') =>
               schema,
               required,
               in: paramIn,
-              description: description[description.length - 1] ?? '',
+              ...(description.length > 0
+                ? { description: description[description.length - 1] }
+                : {}),
             })),
           ),
         ),
@@ -150,15 +152,15 @@ const routeSummary = (init: Node) => {
   }
 };
 
-const routeDescription = (init: Node) => {
+const routeDescription = (init: Node): { description?: string; isPrivate: boolean } => {
   return pipe(
     E.fromNullable('No symbol for initializer')(init.getSymbol()),
     E.chain((sym) =>
       E.fromNullable('No value declaration')(
         (sym.getAliasedSymbol() ?? sym).getValueDeclaration(),
       ),
     ),
-    E.chain((decl) => {
+    E.chain((decl): E.Either<string, { description?: string; isPrivate: boolean }> => {
       let current: Node | undefined = decl;
       while (current !== undefined) {
         const comments = current.getLeadingCommentRanges();
@@ -182,7 +184,7 @@ const routeDescription = (init: Node) => {
       }
       return E.left('no comment found');
     }),
-    E.getOrElse(() => ({ description: '', isPrivate: false })),
+    E.getOrElseW(() => ({ isPrivate: false })),
   );
 };