feat(openapi/upload): docs + DX enhancements for slugs vs. legacy IDs (#1309)

kanadgupta · web-flow · commit 5272a7e8c03f · 2025-07-29T13:48:52.000-05:00
## 🧰 Changes folks have been a little confused with the slug vs. legacy id parameter paradigm, so this PR enhances the DX and docs for `rdme openapi upload` in a few ways: - [x] expanded upon the whole legacy ID ➡️ slug change in the migration guide - [x] added a little bit of smarter DX for when a user passes in a `--slug <some slug that looks eerily like a mongo object id>` (which is a no-no since object IDs should be using `--legacy-id`): - if a user passes an object ID and it matches one of the legacy IDs in the API definitions list, it'll prompt the user before updating that API definition, and emit a warning telling them what the correct slug should be. if this is run in CI, it'll throw an error that tells them the correct file name. <img width="2906" height="219" alt="CleanShot 2025-07-17 at 17 28 43@2x" src="https://github.com/user-attachments/assets/2bf7f7b2-7b27-4605-8bab-aa25f79d24cf" /> - if the object ID doesn't match anything, it'll proceed as normal but emit a warning telling them to check out our migration guide, just in case. <img width="2512" height="196" alt="CleanShot 2025-07-17 at 17 31 55@2x" src="https://github.com/user-attachments/assets/d505d174-1f65-43fb-a5ff-197db1c03ddd" /> - [x] if a user passes the `--legacy-id` flag and there aren't any matches but there are legacy API definitions in the project, the error message will suggest those - [x] if a user passes the `--legacy-id` flag and there is a match, the warning is now a bit more custom tailored and will inform them of what the slug is and encourage them to use that instead ## 🧬 QA & Testing wrote a bunch of tests for every permutation of this logic, and confirmed it works against my lil clone of our internal handbook.
diff --git a/__tests__/commands/openapi/__snapshots__/upload.test.ts.snap b/__tests__/commands/openapi/__snapshots__/upload.test.ts.snap
@@ -20,11 +20,28 @@ See more help with --help],
 }
 `;
 
-exports[`rdme openapi upload > given that the "--legacy-id" flag is passed > should error if no matching API definition found 1`] = `
+exports[`rdme openapi upload > given that the "--legacy-id" flag is passed > should error if no matching API definition found (and there are no existing definitions) 1`] = `
 {
-  "error": [Error: No API definition found with legacy ID 1234567890.],
-  "stderr": " ›   Warning: The "legacy-id" flag has been deprecated.
-- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+  "error": [Error: No API definition found with legacy ID 1234567890. No existing definitions were found. Did you mean to use the \`--slug\` flag instead?],
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+",
+  "stdout": "",
+}
+`;
+
+exports[`rdme openapi upload > given that the "--legacy-id" flag is passed > should error if no matching API definition found (and there are several existing definitions) 1`] = `
+{
+  "error": [Error: No API definition found with legacy ID 1234567890. 3 file(s) were found — if you meant to update one of those, pass in one of these slugs via the \`--slug\` flag: \`file1.json\`, \`file2.json\`, \`file3.json\`.],
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+",
+  "stdout": "",
+}
+`;
+
+exports[`rdme openapi upload > given that the "--legacy-id" flag is passed > should error if no matching API definition found (and there is a single existing definition) 1`] = `
+{
+  "error": [Error: No API definition found with legacy ID 1234567890. 1 file was found — did you mean to update that? If so, try replacing \`--legacy-id 1234567890\` with \`--slug file1.json\`.],
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
 ",
   "stdout": "",
 }
@@ -36,8 +53,10 @@ exports[`rdme openapi upload > given that the "--legacy-id" flag is passed > sho
     "status": "done",
     "uri": "/branches/1.0.0/apis/legacy-spec.json",
   },
-  "stderr": " ›   Warning: The "legacy-id" flag has been deprecated.
-- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+ ›   Warning: The \`--legacy-id\` flag will be removed in a future version. We 
+ ›   recommend passing \`--slug legacy-spec.json\` for maximum compatibility and 
+ ›   readability.
 - Updating your API definition to ReadMe...
 ✔ Updating your API definition to ReadMe... done!
 ",
@@ -101,6 +120,34 @@ exports[`rdme openapi upload > given that the API definition is a URL > should u
 }
 `;
 
+exports[`rdme openapi upload > given that the API definition is a local file > and the \`--slug\` flag is passed > should emit a warning if an object ID is passed and no legacy match is found 1`] = `
+{
+  "result": {
+    "status": "done",
+    "uri": "/branches/1.0.0/apis/687855c3600c6e14c79a94cb.json",
+  },
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+ ›   Warning: The slug you provided looks like a legacy API definition ID, and 
+ ›   these IDs are now deprecated in ReadMe. More info here: 
+ ›   https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md
+ ›   #v10-openapi-upload-command-updates
+- Creating your API definition to ReadMe...
+✔ Creating your API definition to ReadMe... done!
+",
+  "stdout": "🚀 Your API definition (687855c3600c6e14c79a94cb.json) was successfully created in ReadMe!
+",
+}
+`;
+
+exports[`rdme openapi upload > given that the API definition is a local file > and the \`--slug\` flag is passed > should exit if an object ID is passed and a legacy match is found but the user declines the prompt 1`] = `
+{
+  "error": [Error: Aborting, no changes were made.],
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+",
+  "stdout": "",
+}
+`;
+
 exports[`rdme openapi upload > given that the API definition is a local file > and the \`--slug\` flag is passed > should handle a slug with a valid but mismatching file extension 1`] = `
 {
   "error": [Error: Please provide a valid file extension that matches the extension on the file you provided. Must be \`.json\`, \`.yaml\`, or \`.yml\`.],
@@ -119,6 +166,25 @@ exports[`rdme openapi upload > given that the API definition is a local file > a
 }
 `;
 
+exports[`rdme openapi upload > given that the API definition is a local file > and the \`--slug\` flag is passed > should prompt the user before updating if an object ID is passed and a legacy match is found 1`] = `
+{
+  "result": {
+    "status": "done",
+    "uri": "/branches/1.0.0/apis/legacy-spec.json",
+  },
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+ ›   Warning: The slug you provided matches a legacy API definition ID and 
+ ›   these IDs are now deprecated in ReadMe. To ensure maximum compatibility 
+ ›   going forward, we recommend updating your \`--slug\` flag to  
+ ›   \`legacy-spec.json\`.
+- Updating your API definition to ReadMe...
+✔ Updating your API definition to ReadMe... done!
+",
+  "stdout": "🚀 Your API definition (legacy-spec.json) was successfully updated in ReadMe!
+",
+}
+`;
+
 exports[`rdme openapi upload > given that the API definition is a local file > and the \`--slug\` flag is passed > should use the provided slug (includes file extension) as the filename 1`] = `
 {
   "result": {
@@ -149,6 +215,15 @@ exports[`rdme openapi upload > given that the API definition is a local file > a
 }
 `;
 
+exports[`rdme openapi upload > given that the API definition is a local file > and the command is being run in a CI environment > should error out if an object ID is passed and there is a legacy match found 1`] = `
+{
+  "error": [Error: The slug you provided matches a legacy API definition ID, which have been deprecated in ReadMe. To fix this, update your \`--slug\` flag to  \`legacy-spec.json\`.],
+  "stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
+",
+  "stdout": "",
+}
+`;
+
 exports[`rdme openapi upload > given that the API definition is a local file > and the command is being run in a CI environment > should overwrite an existing API definition without asking for confirmation 1`] = `
 {
   "result": {
diff --git a/__tests__/commands/openapi/upload.test.ts b/__tests__/commands/openapi/upload.test.ts
@@ -192,20 +192,94 @@ describe('rdme openapi upload', () => {
         mock.done();
       });
 
+      it('should emit a warning if an object ID is passed and no legacy match is found', async () => {
+        const customSlug = '687855c3600c6e14c79a94cb';
+        const customSlugWithExtension = `${customSlug}.json`;
+        const mock = getAPIv2Mock({ authorization: `Bearer ${key}` })
+          .get(`/branches/${branch}/apis`)
+          .reply(200, { data: [] })
+          .post(`/branches/${branch}/apis`, body =>
+            body.match(`form-data; name="schema"; filename="${customSlugWithExtension}"`),
+          )
+          .reply(200, {
+            data: {
+              upload: { status: 'done' },
+              uri: `/branches/${branch}/apis/${customSlugWithExtension}`,
+            },
+          });
+
+        const result = await run(['--branch', branch, filename, '--key', key, '--slug', customSlug]);
+
+        expect(result).toMatchSnapshot();
+
+        mock.done();
+      });
+
+      it('should prompt the user before updating if an object ID is passed and a legacy match is found', async () => {
+        prompts.inject([true]);
+        const customSlug = '687855c3600c6e14c79a94cb';
+        const existingFilename = 'legacy-spec.json';
+        const mock = getAPIv2Mock({ authorization: `Bearer ${key}` })
+          .get(`/branches/${branch}/apis`)
+          .reply(200, { data: [{ legacy_id: customSlug, filename: existingFilename }] })
+          .put(`/branches/${branch}/apis/${existingFilename}`, body =>
+            body.match(`form-data; name="schema"; filename="${existingFilename}"`),
+          )
+          .reply(200, {
+            data: {
+              upload: { status: 'done' },
+              uri: `/branches/${branch}/apis/${existingFilename}`,
+            },
+          });
+
+        const result = await run(['--branch', branch, filename, '--key', key, '--slug', customSlug]);
+
+        expect(result).toMatchSnapshot();
+
+        mock.done();
+      });
+
+      it('should exit if an object ID is passed and a legacy match is found but the user declines the prompt', async () => {
+        prompts.inject([false]);
+        const customSlug = '687855c3600c6e14c79a94cb';
+        const existingFilename = 'legacy-spec.json';
+        const mock = getAPIv2Mock({ authorization: `Bearer ${key}` })
+          .get(`/branches/${branch}/apis`)
+          .reply(200, { data: [{ legacy_id: customSlug, filename: existingFilename }] });
+
+        const result = await run(['--branch', branch, filename, '--key', key, '--slug', customSlug]);
+
+        expect(result).toMatchSnapshot();
+
+        mock.done();
+      });
+
       it('should handle a slug with an invalid file extension', async () => {
         const customSlug = 'custom-slug.yikes';
 
+        const mock = getAPIv2Mock({ authorization: `Bearer ${key}` })
+          .get(`/branches/${branch}/apis`)
+          .reply(200, { data: [] });
+
         const result = await run(['--branch', branch, filename, '--key', key, '--slug', customSlug]);
 
         expect(result).toMatchSnapshot();
+
+        mock.done();
       });
 
       it('should handle a slug with a valid but mismatching file extension', async () => {
         const customSlug = 'custom-slug.yml';
 
+        const mock = getAPIv2Mock({ authorization: `Bearer ${key}` })
+          .get(`/branches/${branch}/apis`)
+          .reply(200, { data: [] });
+
         const result = await run(['--branch', branch, filename, '--key', key, '--slug', customSlug]);
 
         expect(result).toMatchSnapshot();
+
+        mock.done();
       });
     });
 
@@ -390,6 +464,20 @@ describe('rdme openapi upload', () => {
 
         mock.done();
       });
+
+      it('should error out if an object ID is passed and there is a legacy match found', async () => {
+        const customSlug = '687855c3600c6e14c79a94cb';
+        const existingFilename = 'legacy-spec.json';
+        const mock = getAPIv2MockForGHA({ authorization: `Bearer ${key}` })
+          .get(`/branches/${branch}/apis`)
+          .reply(200, { data: [{ legacy_id: customSlug, filename: existingFilename }] });
+
+        const result = await run(['--branch', branch, filename, '--key', key, '--slug', customSlug]);
+
+        expect(result).toMatchSnapshot();
+
+        mock.done();
+      });
     });
 
     describe('given that the `--branch` flag is not set', () => {
@@ -578,7 +666,7 @@ describe('rdme openapi upload', () => {
       putMock.done();
     });
 
-    it('should error if no matching API definition found', async () => {
+    it('should error if no matching API definition found (and there are no existing definitions)', async () => {
       const legacyId = '1234567890';
       prompts.inject([true]);
       const getMock = getAPIv2Mock({ authorization: `Bearer ${key}` })
@@ -591,5 +679,41 @@ describe('rdme openapi upload', () => {
 
       getMock.done();
     });
+
+    it('should error if no matching API definition found (and there is a single existing definition)', async () => {
+      const legacyId = '1234567890';
+      prompts.inject([true]);
+      const getMock = getAPIv2Mock({ authorization: `Bearer ${key}` })
+        .get(`/branches/${branch}/apis`)
+        .reply(200, {
+          data: [{ legacy_id: 'some-mismatching-id1', filename: 'file1.json' }],
+        });
+
+      const result = await run(['--branch', branch, filename, '--key', key, '--legacy-id', legacyId]);
+
+      expect(result).toMatchSnapshot();
+
+      getMock.done();
+    });
+
+    it('should error if no matching API definition found (and there are several existing definitions)', async () => {
+      const legacyId = '1234567890';
+      prompts.inject([true]);
+      const getMock = getAPIv2Mock({ authorization: `Bearer ${key}` })
+        .get(`/branches/${branch}/apis`)
+        .reply(200, {
+          data: [
+            { legacy_id: 'some-mismatching-id1', filename: 'file1.json' },
+            { legacy_id: 'some-mismatching-id2', filename: 'file2.json' },
+            { legacy_id: 'some-mismatching-id3', filename: 'file3.json' },
+          ],
+        });
+
+      const result = await run(['--branch', branch, filename, '--key', key, '--legacy-id', legacyId]);
+
+      expect(result).toMatchSnapshot();
+
+      getMock.done();
+    });
   });
 });
diff --git a/documentation/commands/openapi.md b/documentation/commands/openapi.md
@@ -212,6 +212,9 @@ DESCRIPTION
   If the spec is a URL, the inferred slug is the base file name from the URL (e.g., the slug for
   `https://example.com/docs/petstore.json` will be `petstore.json`).
 
+  For the best and most explicit results, we recommend using the `--slug` flag to set a slug for your API definition,
+  especially if you're managing many API definitions at scale.
+
 EXAMPLES
   You can pass in a file name like so:
 
diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md
@@ -120,7 +120,11 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi
    If you previously uploaded API definitions to ReadMe via `rdme openapi`, the command is now `rdme openapi upload`. There are now two main updates:
    - Like the Markdown uploading commands above, there is no prompt to select your ReadMe project version if you omit the `--version` flag. It now defaults to `stable` (i.e., your main ReadMe project version). This flag has also been renamed to `--branch`.
 
-   - The flag paradigms have been simplified based on community feedback. Previously with `openapi`, the `--id` flag was a hexadecimal object ID that required an initial upload to ReadMe, which made it difficult to upsert API definitions and manage many at scale (and workarounds were added after the fact in the form of the `--create` and `--update` flags). With `openapi upload`, the `--id` flag has been renamed to `--slug` and is now optional. The slug (i.e., the unique identifier for your API definition resource in ReadMe) is inferred from the file path or URL to your API definition.
+   - The flag paradigms have been simplified based on community feedback. With the previous command, the `--id` flag was a hexadecimal object ID (e.g., `687855c3600c6e14c79a94cb`). These IDs lacked readability and required an initial upload to ReadMe to obtain, which made it difficult to upsert API definitions and manage many at scale. With `openapi upload` and ReadMe Refactored, **the `--id` flag has been removed in favor of `--slug`**. Slugs are now the unique identifier for an API definition resource in ReadMe.
+
+     Unlike the object ID paradigm that was previously used with `--id`, the `--slug` flag enables you to define a slug during initial upload. While we encourage you to use this flag and especially encourage slugs that are human-readable and descriptive, `--slug` is technically optional. When omitted, your API definition's slug is inferred from the file path or URL to your API definition.
+
+     If you've migrated your project from our legacy platform and you'd like to continue syncing any previously uploaded API definitions via `rdme`, we recommend either 1) looking at the post-migration file name in ReadMe and using the `--slug` flag to refer to that (recommended!) or 2) passing the legacy object ID reference via the `--legacy-id` flag (this is a hidden flag and should not be used in new workflows).
 
    Read more in [the `rdme openapi upload` command docs](https://github.com/readmeio/rdme/blob/v10/documentation/commands/openapi.md#rdme-openapi-upload-spec) and in [the ReadMe API migration guide](https://docs.readme.com/main/reference/api-migration-guide).
 
diff --git a/src/commands/openapi/upload.ts b/src/commands/openapi/upload.ts
