fix: create a response description if one is missing

package.json

@@ -37,6 +37,7 @@
     "release": "npx conventional-changelog-cli -i CHANGELOG.md -s && git add CHANGELOG.md"
   },
   "dependencies": {
+    "@readme/http-status-codes": "^7.2.0",
     "js-yaml": "^4.1.0",
     "jsonc-parser": "3.2.0",
     "lodash.camelcase": "^4.3.0",

src/index.js

@@ -8,6 +8,7 @@ const {
   promises: { writeFile, readFile },
 } = require('fs');
 
+const { getStatusCodeMessage } = require('@readme/http-status-codes');
 const { dump } = require('js-yaml');
 const jsonc = require('jsonc-parser');
 const camelCase = require('lodash.camelcase');
@@ -552,6 +553,16 @@ function parseResponseFromExamples(responses, responseHeaders) {
         code = 'default';
       }
 
+      // The OpenAPI spec requires that `description` be present on responses with content so
+      // we'll make it match the message that cooresponds to the HTTP status code.
+      if (!description) {
+        try {
+          description = getStatusCodeMessage({ code });
+        } catch (err) {
+          description = code;
+        }
+      }
+
       if (code in statusMap) {
         if (!(language in statusMap[code].bodies)) {
           statusMap[code].bodies[language] = [];

test/resources/output/ResponsesWithoutHTTPStatusCode.yml

@@ -24,6 +24,7 @@ paths:
                 avatar: https://cdn.fakercloud.com/avatars/nelsonjoyce_128.jpg
       responses:
         default:
+          description: default
           headers:
             Server:
               schema:

types/globals.d.ts

@@ -0,0 +1 @@
+declare module '@readme/http-status-codes';