chore: update local openapi snapshot (#1194)

## 🧰 Changes

this PR updates our APIv2 openapi description as part of @emilyskuo's
work in #1175 and chunks out the OAS into its own dedicated file since
it's absolutely massive. you can check out the diff of the file changes
[here](next...1346b8b).

i tried messing around with JSON module imports so we can eventually
automate these updates more easily, but we lose out on a lot of good
strict typing that we currently have with `as const satisfies
OASDocument`. annoying!

## 🧬 QA & Testing

no functional changes. do tests still pass?

Author: kanadgupta

__tests__/helpers/get-api-mock.ts

@@ -2,7 +2,7 @@ import nock from 'nock';
 
 import config from '../../src/lib/config.js';
 import { getUserAgent } from '../../src/lib/readmeAPIFetch.js';
-import { readmeAPIv2Oas } from '../../src/lib/types.js';
+import readmeAPIv2Oas from '../../src/lib/types/openapiDoc.js';
 
 import { mockVersion } from './oclif.js';
 

src/lib/readmeAPIFetch.ts

@@ -14,7 +14,7 @@ import { git } from './createGHA/index.js';
 import { getPkgVersion } from './getPkg.js';
 import isCI, { ciName, isGHA } from './isCI.js';
 import { debug, warn } from './logger.js';
-import { readmeAPIv2Oas } from './types.js';
+import readmeAPIv2Oas from './types/openapiDoc.js';
 
 const SUCCESS_NO_CONTENT = 204;
 

src/lib/syncPagePath.ts

@@ -1,5 +1,5 @@
 import type { PageMetadata } from './readPage.js';
-import type { GuidesRequestRepresentation } from './types.js';
+import type { GuidesRequestRepresentation } from './types/index.js';
 import type DocsUploadCommand from '../commands/docs/upload.js';
 
 import fs from 'node:fs/promises';
@@ -17,7 +17,7 @@ import promptTerminal from './promptWrapper.js';
 import readdirRecursive from './readdirRecursive.js';
 import { fetchMappings, fetchSchema } from './readmeAPIFetch.js';
 import readPage from './readPage.js';
-import { categoryUriRegexPattern, parentUriRegexPattern } from './types.js';
+import { categoryUriRegexPattern, parentUriRegexPattern } from './types/index.js';
 
 /**
  * Commands that use this file for syncing Markdown via APIv2.

src/lib/types/index.ts

@@ -0,0 +1,26 @@
+import type { FromSchema } from 'json-schema-to-ts';
+
+import readmeAPIv2Oas from './openapiDoc.js';
+
+export const categoryUriRegexPattern =
+  readmeAPIv2Oas.paths['/versions/{version}/guides'].post.requestBody.content['application/json'].schema.properties
+    .category.properties.uri.pattern;
+
+export const parentUriRegexPattern =
+  readmeAPIv2Oas.paths['/versions/{version}/guides'].post.requestBody.content['application/json'].schema.properties
+    .parent.properties.uri.pattern;
+
+type guidesRequestBodySchema =
+  (typeof readmeAPIv2Oas)['paths']['/versions/{version}/guides/{slug}']['patch']['requestBody']['content']['application/json']['schema'];
+
+/**
+ * Derived from our API documentation, this is the schema for the `guides` object
+ * as we send it to the ReadMe API.
+ *
+ * This is only for TypeScript type-checking purposes — we use ajv
+ * to validate the user's schema during runtime.
+ */
+export type GuidesRequestRepresentation = FromSchema<
+  guidesRequestBodySchema,
+  { keepDefaultedPropertiesOptional: true }
+>;