diff --git a/__tests__/helpers/get-api-mock.ts b/__tests__/helpers/get-api-mock.ts index 725e984c1..b752c6583 100644 --- a/__tests__/helpers/get-api-mock.ts +++ b/__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'; diff --git a/src/lib/readmeAPIFetch.ts b/src/lib/readmeAPIFetch.ts index 2f245fb0f..d888dddd1 100644 --- a/src/lib/readmeAPIFetch.ts +++ b/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; diff --git a/src/lib/syncPagePath.ts b/src/lib/syncPagePath.ts index 042e47ab0..551d4146f 100644 --- a/src/lib/syncPagePath.ts +++ b/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. diff --git a/src/lib/types/index.ts b/src/lib/types/index.ts new file mode 100644 index 000000000..392aaadee --- /dev/null +++ b/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 } +>; diff --git a/src/lib/types.ts b/src/lib/types/openapiDoc.ts similarity index 92% rename from src/lib/types.ts rename to src/lib/types/openapiDoc.ts index 23fb65733..c0606115d 100644 --- a/src/lib/types.ts +++ b/src/lib/types/openapiDoc.ts @@ -1,14 +1,21 @@ -import type { FromSchema } from 'json-schema-to-ts'; import type { OASDocument } from 'oas/types'; -export const readmeAPIv2Oas = { +/** + * This is a snapshot of the OpenAPI description for ReadMe APIv2. + * + * This is used both for typechecking as well as for runtime validation. + * We use ajv to validate the user data against schemas in this document. + * + * @see {@link https://docs.readme.com/main/openapi/readme-api-v2-beta.json} + */ +const document = { openapi: '3.1.0', info: { description: 'Create beautiful product and API documentation with our developer friendly platform.', version: '2.0.0-beta', title: 'ReadMe API v2 ๐Ÿฆ‰ (BETA)', // @ts-expect-error custom extension - 'x-readme-deploy': '5.271.0', + 'x-readme-deploy': '5.298.0', termsOfService: 'https://readme.com/tos', contact: { name: 'API Support', @@ -30,10 +37,10 @@ export const readmeAPIv2Oas = { '/versions/{version}/apis': { get: { operationId: 'getAPIs', - summary: 'Retrieve all API schemas that a project has.', + summary: 'Get all API definitions', tags: ['APIs'], description: - "Retrieves all of the API schemas that are set up for your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Get all API definitions from your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { type: 'string', pattern: 'stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?' }, @@ -132,10 +139,10 @@ export const readmeAPIv2Oas = { }, post: { operationId: 'createAPI', - summary: 'Create an API', + summary: 'Create an API definition', tags: ['APIs'], description: - "Creates an API in the reference section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Create an API definition in the API Reference section of your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", requestBody: { content: { 'multipart/form-data': { @@ -209,10 +216,10 @@ export const readmeAPIv2Oas = { '/versions/{version}/apis/{filename}': { get: { operationId: 'getAPI', - summary: 'Retrieves information about a specific API schema.', + summary: 'Get an API definition', tags: ['APIs'], description: - "Retrieves information about a specific API schema on your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Get an API definition from your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { type: 'string', pattern: '(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml))' }, @@ -313,12 +320,36 @@ export const readmeAPIv2Oas = { }, }, }, + delete: { + operationId: 'deleteAPI', + summary: 'Delete an API definition', + tags: ['APIs'], + description: + "Delete an API definition from the API Reference section of your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + parameters: [ + { + schema: { type: 'string', pattern: '(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml))' }, + in: 'path', + name: 'filename', + required: true, + description: 'The filename of the API definition to retrieve.', + }, + { + schema: { type: 'string', pattern: 'stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?' }, + in: 'path', + name: 'version', + required: true, + description: 'Project version number or stable.', + }, + ], + responses: { '204': { description: 'No Content' } }, + }, put: { operationId: 'updateAPI', - summary: 'Update an API', + summary: 'Update an API definition', tags: ['APIs'], description: - "Updates an API in the reference section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Updates an API definition in the API Reference section of your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", requestBody: { content: { 'multipart/form-data': { @@ -399,10 +430,10 @@ export const readmeAPIv2Oas = { '/changelogs': { get: { operationId: 'getChangelogs', - summary: 'Get changelogs', + summary: 'Get all changelog entries', tags: ['Changelog'], description: - "Get a collection of changelogs.\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Get all changelog entries from your ReadMe project.\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { type: 'number', minimum: 1, default: 1 }, @@ -578,10 +609,10 @@ export const readmeAPIv2Oas = { '/changelogs/{identifier}': { get: { operationId: 'getChangelog', - summary: 'Get changelog', + summary: 'Get a changelog entry', tags: ['Changelog'], description: - "Returns the changelog.\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Get a changelog entry from your ReadMe project.\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { @@ -735,7 +766,7 @@ export const readmeAPIv2Oas = { summary: 'Create a custom page', tags: ['Custom Pages'], description: - "Create a new custom page. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Create a custom page in your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", requestBody: { content: { 'application/json': { @@ -942,10 +973,10 @@ export const readmeAPIv2Oas = { }, get: { operationId: 'getCustomPages', - summary: 'Get custom pages', + summary: 'Get all custom pages', tags: ['Custom Pages'], description: - "Get a collection of custom pages. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Get all custom pages from your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { type: 'string', pattern: 'stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?' }, @@ -1089,10 +1120,10 @@ export const readmeAPIv2Oas = { '/versions/{version}/custom_pages/{slug}': { get: { operationId: 'getCustomPage', - summary: 'Retrieve a custom page', + summary: 'Get a custom page', tags: ['Custom Pages'], description: - "Retrieves a custom page from the custom page section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Get a custom page from your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { type: 'string', pattern: 'stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?' }, @@ -1240,7 +1271,7 @@ export const readmeAPIv2Oas = { summary: 'Delete a custom page', tags: ['Custom Pages'], description: - "Deletes a custom page from the custom page section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Delete a custom page from your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { type: 'string', pattern: 'stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?' }, @@ -1264,7 +1295,7 @@ export const readmeAPIv2Oas = { summary: 'Update a custom page', tags: ['Custom Pages'], description: - "Updates a custom page in the custompage section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Update an existing custom page in your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", requestBody: { content: { 'application/json': { @@ -1478,10 +1509,10 @@ export const readmeAPIv2Oas = { '/versions/{version}/guides': { post: { operationId: 'createGuide', - summary: 'Create a guide', + summary: 'Create a guides page', tags: ['Guides'], description: - "Creates a page in the guides section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Create a page in the Guides section of your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", requestBody: { content: { 'application/json': { @@ -1872,10 +1903,10 @@ export const readmeAPIv2Oas = { '/versions/{version}/guides/{slug}': { get: { operationId: 'getGuide', - summary: 'Retrieve a guide', + summary: 'Get a guides page', tags: ['Guides'], description: - "Retrieves a page from the guides section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Get a page from the Guides section of your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { type: 'string', pattern: 'stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?' }, @@ -2125,10 +2156,10 @@ export const readmeAPIv2Oas = { }, delete: { operationId: 'deleteGuide', - summary: 'Delete a guide', + summary: 'Delete a guides page', tags: ['Guides'], description: - "Deletes a page from the guides section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Delete a page from the Guides section of your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", parameters: [ { schema: { type: 'string', pattern: 'stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?' }, @@ -2149,10 +2180,10 @@ export const readmeAPIv2Oas = { }, patch: { operationId: 'updateGuide', - summary: 'Update a guide', + summary: 'Update a guides page', tags: ['Guides'], description: - "Updates a page in the guides section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + "Updates an existing page in the Guides section of your ReadMe project. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", requestBody: { content: { 'application/json': { @@ -2544,2997 +2575,3026 @@ export const readmeAPIv2Oas = { }, }, }, - '/versions/{version}/reference': { - post: { - operationId: 'createReference', - summary: 'Create a reference', - tags: ['API Reference'], + '/projects/me': { + get: { + operationId: 'getProject', + summary: 'Get project metadata', + tags: ['Projects'], description: - "Creates a reference page in the API Reference section of your developer hub. \n\n>๐Ÿ“˜\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", - requestBody: { - content: { - 'application/json': { - schema: { - type: 'object', - properties: { - allow_crawlers: { - type: 'string', - enum: ['enabled', 'disabled'], - default: 'enabled', - description: 'Allow indexing by robots.', - }, - category: { - type: 'object', - properties: { - uri: { - type: 'string', - pattern: - '\\/versions\\/(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)\\/categories\\/(guides|reference)\\/((.*))', - description: 'A URI to the category resource.', - }, - }, - required: ['uri'], - additionalProperties: false, - }, - content: { - type: 'object', - properties: { - body: { type: 'string', nullable: true }, - excerpt: { type: 'string', nullable: true }, - link: { - type: 'object', - properties: { - url: { type: 'string', nullable: true }, - new_tab: { type: 'boolean', nullable: true }, - }, - additionalProperties: false, - description: - 'Information about where this page should redirect to; only available when `type` is `link`.', - }, - next: { - type: 'object', - properties: { - description: { type: 'string', nullable: true }, - pages: { - type: 'array', - items: { - anyOf: [ - { - type: 'object', - properties: { - slug: { type: 'string' }, - title: { type: 'string', nullable: true }, - type: { type: 'string', enum: ['basic', 'endpoint'] }, - }, - required: ['slug', 'title', 'type'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - title: { type: 'string', nullable: true }, - type: { type: 'string', enum: ['link'] }, - url: { type: 'string' }, - }, - required: ['title', 'type', 'url'], - additionalProperties: false, - }, - ], - }, - }, + "Returns data about your project.\n\n>๐Ÿšง ReadMe's API v2 is currently in beta.\n> This API and its docs are a work in progress. While we donโ€™t expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!", + responses: { + '200': { + description: 'OK', + content: { + 'application/json': { + schema: { + type: 'object', + properties: { + data: { + type: 'object', + properties: { + allow_crawlers: { + type: 'string', + enum: ['enabled', 'disabled'], + default: 'enabled', + description: 'Allow indexing by robots.', }, - additionalProperties: false, - }, - }, - additionalProperties: false, - }, - href: { - type: 'object', - properties: { - dash: { type: 'string', format: 'uri', description: 'A URL to this page in your ReadMe Dash.' }, - }, - additionalProperties: false, - }, - metadata: { - type: 'object', - properties: { - description: { type: 'string', nullable: true }, - keywords: { type: 'string', nullable: true }, - title: { type: 'string', nullable: true }, - image: { - type: 'object', - properties: { uri: { type: 'string', pattern: '\\/images\\/([a-f\\d]{24})', nullable: true } }, - additionalProperties: false, - }, - }, - additionalProperties: false, - }, - parent: { - type: 'object', - properties: { - uri: { - type: 'string', - pattern: - '\\/versions\\/(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)', - nullable: true, - }, - }, - additionalProperties: false, - }, - privacy: { - type: 'object', - properties: { - view: { type: 'string', enum: ['public', 'anyone_with_link'], default: 'anyone_with_link' }, - }, - additionalProperties: false, - }, - renderable: { - type: 'object', - properties: { - status: { - type: 'boolean', - default: true, - description: 'A flag for if the page is renderable or not.', - }, - error: { type: 'string', nullable: true }, - message: { type: 'string', nullable: true }, - }, - additionalProperties: false, - }, - slug: { - allOf: [{ type: 'string' }, { type: 'string', minLength: 1 }], - description: 'The accessible URL slug for the page.', - }, - state: { type: 'string', enum: ['current', 'deprecated'], default: 'current' }, - title: { type: 'string' }, - type: { type: 'string', enum: ['api_config', 'basic', 'endpoint', 'link'], default: 'basic' }, - connections: { - type: 'object', - properties: { - recipes: { - type: 'array', - items: { + api_designer: { type: 'object', properties: { - uri: { + allow_editing: { type: 'string', - pattern: - '\\/versions\\/(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)\\/recipes\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)', - description: - 'URI of the recipe that this API reference is connected to. The recipe and API reference must exist within the same version.', + enum: ['enabled', 'disabled'], + default: 'enabled', + description: 'API Designer is enabled for this project.', }, }, additionalProperties: false, }, - nullable: true, - }, - }, - additionalProperties: false, - }, - position: { type: 'number' }, - api_config: { type: 'string', enum: ['authentication', 'getting-started', 'my-requests'] }, - api: { - type: 'object', - properties: { - method: { - type: 'string', - enum: ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'], - description: 'The endpoint HTTP method.', - }, - path: { type: 'string', description: 'The endpoint path.' }, - schema: { nullable: true }, - stats: { - type: 'object', - properties: { - additional_properties: { - type: 'boolean', - default: false, - description: - 'This API operation uses `additionalProperties` for handling extra schema properties.', - }, - callbacks: { - type: 'boolean', - default: false, - description: 'This API operation has `callbacks` documented.', - }, - circular_references: { - type: 'boolean', - default: false, - description: 'This API operation contains `$ref` schema pointers that resolve to itself.', - }, - common_parameters: { - type: 'boolean', - default: false, - description: 'This API operation utilizes common parameters set at the path level.', - }, - discriminators: { - type: 'boolean', - default: false, - description: - 'This API operation utilizes `discriminator` for discriminating between different parts in a polymorphic schema.', - }, - links: { - type: 'boolean', - default: false, - description: 'This API operation has `links` documented.', - }, - polymorphism: { - type: 'boolean', - default: false, - description: 'This API operation contains polymorphic schemas.', - }, - server_variables: { - type: 'boolean', - default: false, - description: - 'This API operation has composable variables configured for its server definition.', - }, - style: { - type: 'boolean', - default: false, - description: 'This API operation has parameters that have specific `style` serializations.', - }, - webhooks: { - type: 'boolean', - default: false, - description: 'This API definition has `webhooks` documented.', - }, - xml: { - type: 'boolean', - default: false, - description: 'This API operation has parameters or schemas that serialize to XML.', - }, - references: { - type: 'boolean', - description: - 'This API operation, after being dereferenced, has `x-readme-ref-name` entries defining what the original `$ref` schema pointers were named.', - }, - }, - additionalProperties: false, - description: 'OpenAPI features that are utilized within this API operation.', - }, - source: { - type: 'string', - enum: ['api', 'apidesigner', 'apieditor', 'bidi', 'form', 'rdme', 'rdme_github', 'url'], - nullable: true, - }, - uri: { - type: 'string', - pattern: - '\\/versions\\/(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)\\/apis\\/((([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml)))', - nullable: true, - }, - }, - additionalProperties: false, - }, - }, - required: ['category', 'title'], - additionalProperties: false, - }, - }, - }, - required: true, - }, - parameters: [ - { - schema: { type: 'string', pattern: 'stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?' }, - in: 'path', - name: 'version', - required: true, - description: 'Project version number or stable.', - }, - ], - responses: { - '201': { - description: 'Created', - content: { - 'application/json': { - schema: { - type: 'object', - properties: { - data: { - type: 'object', - properties: { - allow_crawlers: { - type: 'string', - enum: ['enabled', 'disabled'], - default: 'enabled', - description: 'Allow indexing by robots.', - }, - category: { - type: 'object', - properties: { - uri: { - type: 'string', - pattern: - '\\/versions\\/(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)\\/categories\\/(guides|reference)\\/((.*))', - description: 'A URI to the category resource.', - }, - }, - required: ['uri'], - additionalProperties: false, - }, - content: { + appearance: { type: 'object', properties: { - body: { type: 'string', nullable: true }, - excerpt: { type: 'string', nullable: true }, - link: { + brand: { type: 'object', properties: { - url: { type: 'string', nullable: true }, - new_tab: { - type: 'boolean', - nullable: true, - description: 'Should this URL be opened up in a new tab?', - }, + primary_color: { type: 'string', nullable: true }, + link_color: { type: 'string', nullable: true }, + theme: { type: 'string', enum: ['system', 'light', 'dark'], default: 'light' }, }, - required: ['url', 'new_tab'], + required: ['primary_color', 'link_color'], additionalProperties: false, - description: - 'Information about where this page should redirect to; only available when `type` is `link`.', }, - next: { + changelog: { type: 'object', properties: { - description: { type: 'string', nullable: true }, - pages: { - type: 'array', - items: { - anyOf: [ - { - type: 'object', - properties: { - slug: { type: 'string' }, - title: { type: 'string', nullable: true }, - type: { type: 'string', enum: ['basic', 'endpoint'] }, - }, - required: ['slug', 'title', 'type'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - title: { type: 'string', nullable: true }, - type: { type: 'string', enum: ['link'] }, - url: { type: 'string' }, - }, - required: ['title', 'type', 'url'], - additionalProperties: false, - }, - ], - }, + layout: { type: 'string', enum: ['collapsed', 'continuous'], default: 'collapsed' }, + show_author: { + type: 'boolean', + default: true, + description: 'Should the changelog author be shown?', + }, + show_exact_date: { + type: 'boolean', + default: false, + description: + 'Should the exact date of the changelog entry be shown, or should it be relative?', }, }, - required: ['description', 'pages'], additionalProperties: false, }, - }, - required: ['body', 'excerpt', 'link', 'next'], - additionalProperties: false, - }, - href: { - type: 'object', - properties: { - dash: { - type: 'string', - format: 'uri', - description: 'A URL to this page in your ReadMe Dash.', - }, - }, - required: ['dash'], - additionalProperties: false, - }, - metadata: { - type: 'object', - properties: { - description: { type: 'string', nullable: true }, - image: { + custom_code: { type: 'object', properties: { - uri: { + css: { type: 'string', - pattern: '\\/images\\/([a-f\\d]{24})', nullable: true, description: - 'A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`.', + 'A chunk of custom CSS that you can use to override default CSS that we provide.', + }, + js: { + type: 'string', + nullable: true, + description: + 'A chunk of custom JS that you can use to override or add new behaviors to your documentation. Please note that we do not do any validation on the code that goes in here so you have the potential to negatively impact your users with broken code.', + }, + html: { + type: 'object', + properties: { + header: { + type: 'string', + nullable: true, + description: + 'A block of custom HTML that will be added to your `` tag. Good for things like `` tags or loading external CSS.', + }, + home_footer: { + type: 'string', + nullable: true, + description: + 'A block of custom HTML that will appear in a `