fix(openapi/upload): improved handling for YAML files (#1154)

| 🚥 Resolves RM-11893, #1142 |
| :------------------- |

## 🧰 Changes

When uploading an API definition, `rdme` converts all files to JSON,
which means that YAML files are uploaded in JSON but with the file
extension of `.yaml` or `.yml`. This will convert files originally in
YAML back to YAML before uploading to ReadMe.

## 🧬 QA & Testing

Upload a spec in YAML and confirm in GitHug that it's been stored in
YAML. Also confirm that JSON specs are uploaded in JSON as well.

---------

Co-authored-by: Kanad Gupta <[email protected]>

Author: emilyskuo

__tests__/commands/openapi/__snapshots__/upload.test.ts.snap

@@ -233,7 +233,7 @@ exports[`rdme openapi upload > given that the API definition is a local file > g
 }
 `;
 
-exports[`rdme openapi upload > given that the API definition is a local file > should create a new API definition in ReadMe 1`] = `
+exports[`rdme openapi upload > given that the API definition is a local file > should create a new JSON API definition in ReadMe 1`] = `
 {
   "result": {
     "status": "done",
@@ -252,6 +252,25 @@ exports[`rdme openapi upload > given that the API definition is a local file > s
 }
 `;
 
+exports[`rdme openapi upload > given that the API definition is a local file > should create a new YAML API definition in ReadMe 1`] = `
+{
+  "result": {
+    "status": "done",
+    "uri": "/versions/1.0.0/apis/__tests____fixtures__postmanpetstore.collection.yaml",
+  },
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/postman/petstore.collection.yaml...
+ ›   Warning: The slug of your API Definition will be set to 
+ ›   __tests____fixtures__postmanpetstore.collection.yaml in ReadMe. This slug 
+ ›   is not visible to your end users. To set this slug to something else, use 
+ ›   the \`--slug\` flag.
+- Creating your API definition to ReadMe...
+✔ Creating your API definition to ReadMe... done!
+",
+  "stdout": "🚀 Your API definition (__tests____fixtures__postmanpetstore.collection.yaml) was successfully created in ReadMe!
+",
+}
+`;
+
 exports[`rdme openapi upload > given that the API definition is a local file > should handle upload failures 1`] = `
 {
   "error": [Error: Your API definition upload failed with an unexpected error. Please get in touch with us at support@readme.io.],

__tests__/commands/openapi/upload.test.ts

@@ -12,8 +12,10 @@ import { after, before } from '../../helpers/setup-gha-env.js';
 const key = 'rdme_123';
 const version = '1.0.0';
 const filename = '__tests__/__fixtures__/petstore-simple-weird-version.json';
+const yamlFile = '__tests__/__fixtures__/postman/petstore.collection.yaml';
 const fileUrl = 'https://example.com/openapi.json';
 const slugifiedFilename = slugify.default(filename);
+const slugifiedYamlFile = slugify.default(yamlFile);
 
 describe('rdme openapi upload', () => {
   let run: (args?: string[]) => OclifOutput;
@@ -30,12 +32,12 @@ describe('rdme openapi upload', () => {
   });
 
   describe('given that the API definition is a local file', () => {
-    it('should create a new API definition in ReadMe', async () => {
+    it('should create a new JSON API definition in ReadMe', async () => {
       const mock = getAPIv2Mock({ authorization: `Bearer ${key}` })
         .get(`/versions/${version}/apis`)
         .reply(200, { data: [] })
         .post(`/versions/${version}/apis`, body =>
-          body.match(`form-data; name="schema"; filename="${slugifiedFilename}"`),
+          body.match(`form-data; name="schema"; filename="${slugifiedFilename}"\r\nContent-Type: application/json`),
         )
         .reply(200, {
           data: {
@@ -50,6 +52,26 @@ describe('rdme openapi upload', () => {
       mock.done();
     });
 
+    it('should create a new YAML API definition in ReadMe', async () => {
+      const mock = getAPIv2Mock({ authorization: `Bearer ${key}` })
+        .get(`/versions/${version}/apis`)
+        .reply(200, { data: [] })
+        .post(`/versions/${version}/apis`, body =>
+          body.match(`form-data; name="schema"; filename="${slugifiedYamlFile}"\r\nContent-Type: application/x-yaml`),
+        )
+        .reply(200, {
+          data: {
+            upload: { status: 'done' },
+            uri: `/versions/${version}/apis/${slugifiedYamlFile}`,
+          },
+        });
+
+      const result = await run(['--version', version, yamlFile, '--key', key]);
+      expect(result).toMatchSnapshot();
+
+      mock.done();
+    });
+
     it('should update an existing API definition in ReadMe', async () => {
       prompts.inject([true]);
 

package-lock.json

@@ -56,6 +56,7 @@
     "debug": "^4.3.3",
     "gray-matter": "^4.0.1",
     "ignore": "^7.0.0",
+    "js-yaml": "^4.1.0",
     "mime-types": "^2.1.35",
     "oas": "^25.3.0",
     "oas-normalize": "^12.1.0",
@@ -95,7 +96,6 @@
     "alex": "^11.0.0",
     "eslint": "^8.47.0",
     "husky": "^9.0.10",
-    "js-yaml": "^4.1.0",
     "json-schema-to-ts": "^3.1.1",
     "knip": "^5.0.2",
     "nock": "^14.0.0",

package.json

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import nodePath from 'node:path';
 
 import { Flags } from '@oclif/core';
+import yaml from 'js-yaml';
 import ora from 'ora';
 import prompts from 'prompts';
 import slugify from 'slugify';
@@ -115,8 +116,8 @@ export default class OpenAPIUploadCommand extends BaseCommand<typeof OpenAPIUplo
       );
     }
 
+    const fileExtension = nodePath.extname(filename);
     if (this.flags.slug) {
-      const fileExtension = nodePath.extname(filename);
       const slugExtension = nodePath.extname(this.flags.slug);
       if (slugExtension && (!['.json', '.yaml', '.yml'].includes(slugExtension) || fileExtension !== slugExtension)) {
         throw new Error(
@@ -165,19 +166,25 @@ export default class OpenAPIUploadCommand extends BaseCommand<typeof OpenAPIUplo
       this.debug('attaching URL to form data payload');
       body.append('url', specPath);
     } else {
+      const isYaml = fileExtension === '.yaml' || fileExtension === '.yml';
+      // Convert YAML files back to YAML before uploading
+      let specToUpload = preparedSpec;
+      if (isYaml) {
+        specToUpload = yaml.dump(JSON.parse(preparedSpec));
+      }
       // Create a temporary file to write the bundled spec to,
       // which we will then stream into the form data body
-      const { path } = await tmpFile({ prefix: 'rdme-openapi-', postfix: '.json' });
+      const { path } = await tmpFile({ prefix: 'rdme-openapi-', postfix: fileExtension });
       this.debug(`creating temporary file at ${path}`);
-      fs.writeFileSync(path, preparedSpec);
+      fs.writeFileSync(path, specToUpload);
       const stream = fs.createReadStream(path);
 
       this.debug('file and stream created, streaming into form data payload');
       body.append('schema', {
         [Symbol.toStringTag]: 'File',
         name: filename,
         stream: () => stream,
-        type: 'application/json',
+        type: isYaml ? 'application/x-yaml' : 'application/json',
       });
     }