rdme
Version:
ReadMe's official CLI and GitHub Action.
768 lines (767 loc) • 741 kB
JavaScript
/**
* 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)',
'x-readme-deploy': '5.395.0',
termsOfService: 'https://readme.com/tos',
contact: {
name: 'API Support',
url: 'https://docs.readme.com/main/docs/need-more-support',
email: 'support@readme.io',
},
},
components: {
securitySchemes: {
bearer: {
type: 'http',
scheme: 'bearer',
description: 'A bearer token that will be supplied within an `Authentication` header as `bearer <token>`.',
},
},
schemas: {},
},
paths: {
'/projects/{subdomain}/apikeys': {
post: {
operationId: 'createAPIKey',
summary: 'Create an API key',
tags: ['API Keys'],
description: "Create an API key for your ReadMe project.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation 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: { label: { allOf: [{ type: 'string' }, { type: 'string', minLength: 1 }] } },
required: ['label'],
additionalProperties: false,
},
},
},
required: true,
},
parameters: [
{
schema: { type: 'string', pattern: '(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)', maxLength: 30 },
in: 'path',
name: 'subdomain',
required: true,
description: 'The subdomain of your project.',
},
],
responses: {
'201': {
description: 'Created',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
data: {
type: 'object',
properties: {
token: { type: 'string', pattern: 'rdme_\\w+' },
label: { type: 'string', nullable: true },
last_accessed_on: {
type: 'string',
format: 'date-time',
nullable: true,
description: 'An ISO 8601 formatted date for when the API key was last accessed.',
},
created_at: {
type: 'string',
format: 'date-time',
description: 'An ISO 8601 formatted date for when the API key was created.',
},
uri: {
type: 'string',
pattern: '\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)\\/apikeys\\/[a-f\\d]{24}',
},
},
required: ['token', 'label', 'last_accessed_on', 'created_at', 'uri'],
additionalProperties: false,
},
},
required: ['data'],
additionalProperties: false,
},
},
},
},
},
},
get: {
operationId: 'getAPIKeys',
summary: 'Get your API keys',
tags: ['API Keys'],
description: "Get the API keys for your ReadMe project.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation 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 },
in: 'query',
name: 'page',
required: false,
description: 'Used to specify further pages (starts at 1).',
},
{
schema: { type: 'number', minimum: 1, maximum: 100, default: 10 },
in: 'query',
name: 'per_page',
required: false,
description: 'Number of items to include in pagination (up to 100, defaults to 10).',
},
{
schema: { type: 'string', pattern: '(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)', maxLength: 30 },
in: 'path',
name: 'subdomain',
required: true,
description: 'The subdomain of your project.',
},
],
responses: {
'200': {
description: 'OK',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
total: { type: 'number' },
page: { type: 'number' },
per_page: { type: 'number' },
paging: {
type: 'object',
properties: {
next: { type: 'string', nullable: true },
previous: { type: 'string', nullable: true },
first: { type: 'string', nullable: true },
last: { type: 'string', nullable: true },
},
required: ['next', 'previous', 'first', 'last'],
additionalProperties: false,
},
data: {
type: 'array',
items: {
type: 'object',
properties: {
token: { type: 'string', pattern: 'rdme_\\w+' },
label: { type: 'string', nullable: true },
last_accessed_on: {
type: 'string',
format: 'date-time',
nullable: true,
description: 'An ISO 8601 formatted date for when the API key was last accessed.',
},
created_at: {
type: 'string',
format: 'date-time',
description: 'An ISO 8601 formatted date for when the API key was created.',
},
uri: {
type: 'string',
pattern: '\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)\\/apikeys\\/[a-f\\d]{24}',
},
},
required: ['token', 'label', 'last_accessed_on', 'created_at', 'uri'],
additionalProperties: false,
},
},
},
required: ['total', 'page', 'per_page', 'paging', 'data'],
additionalProperties: false,
},
},
},
},
},
},
},
'/projects/{subdomain}/apikeys/{api_key_id}': {
delete: {
operationId: 'deleteAPIKey',
summary: 'Delete an API key',
tags: ['API Keys'],
description: "Delete an API key from your ReadMe project.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation 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-f\\d]{24}' },
in: 'path',
name: 'api_key_id',
required: true,
description: 'The unique identifier for your API key.',
},
{
schema: { type: 'string', pattern: '(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)', maxLength: 30 },
in: 'path',
name: 'subdomain',
required: true,
description: 'The subdomain of your project.',
},
],
responses: { '204': { description: 'No Content' } },
},
get: {
operationId: 'getAPIKey',
summary: 'Get an API key',
tags: ['API Keys'],
description: "Get an API key for your ReadMe project.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation 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-f\\d]{24}' },
in: 'path',
name: 'api_key_id',
required: true,
description: 'The unique identifier for your API key.',
},
{
schema: { type: 'string', pattern: '(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)', maxLength: 30 },
in: 'path',
name: 'subdomain',
required: true,
description: 'The subdomain of your project.',
},
],
responses: {
'200': {
description: 'OK',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
data: {
type: 'object',
properties: {
token: { type: 'string', pattern: 'rdme_\\w+' },
label: { type: 'string', nullable: true },
last_accessed_on: {
type: 'string',
format: 'date-time',
nullable: true,
description: 'An ISO 8601 formatted date for when the API key was last accessed.',
},
created_at: {
type: 'string',
format: 'date-time',
description: 'An ISO 8601 formatted date for when the API key was created.',
},
uri: {
type: 'string',
pattern: '\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)\\/apikeys\\/[a-f\\d]{24}',
},
},
required: ['token', 'label', 'last_accessed_on', 'created_at', 'uri'],
additionalProperties: false,
},
},
required: ['data'],
additionalProperties: false,
},
},
},
},
},
},
patch: {
operationId: 'updateAPIKey',
summary: 'Update an API key',
tags: ['API Keys'],
description: "Update an API key on your ReadMe project.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation 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: { label: { allOf: [{ type: 'string' }, { type: 'string', minLength: 1 }] } },
required: ['label'],
additionalProperties: false,
},
},
},
required: true,
},
parameters: [
{
schema: { type: 'string', pattern: '[a-f\\d]{24}' },
in: 'path',
name: 'api_key_id',
required: true,
description: 'The unique identifier for your API key.',
},
{
schema: { type: 'string', pattern: '(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)', maxLength: 30 },
in: 'path',
name: 'subdomain',
required: true,
description: 'The subdomain of your project.',
},
],
responses: {
'200': {
description: 'OK',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
data: {
type: 'object',
properties: {
token: { type: 'string', pattern: 'rdme_\\w+' },
label: { type: 'string', nullable: true },
last_accessed_on: {
type: 'string',
format: 'date-time',
nullable: true,
description: 'An ISO 8601 formatted date for when the API key was last accessed.',
},
created_at: {
type: 'string',
format: 'date-time',
description: 'An ISO 8601 formatted date for when the API key was created.',
},
uri: {
type: 'string',
pattern: '\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)\\/apikeys\\/[a-f\\d]{24}',
},
},
required: ['token', 'label', 'last_accessed_on', 'created_at', 'uri'],
additionalProperties: false,
},
},
required: ['data'],
additionalProperties: false,
},
},
},
},
},
},
},
'/branches/{branch}/apis': {
get: {
operationId: 'getAPIs',
summary: 'Get all API definitions',
tags: ['APIs'],
description: "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 documentation 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: '(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?',
},
in: 'path',
name: 'branch',
required: true,
description: "Project version number, `stable` for your project's stable version, or a valid branch name.",
},
],
responses: {
'200': {
description: 'OK',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
total: { type: 'number' },
data: {
type: 'array',
items: {
type: 'object',
properties: {
created_at: {
type: 'string',
format: 'date-time',
description: 'An ISO 8601 formatted date for when the API definition was created.',
},
filename: {
type: 'string',
description: 'This is the unique identifier, its filename, for the API definition.',
},
legacy_id: {
type: 'string',
pattern: '[a-f\\d]{24}',
nullable: true,
description: 'The legacy ID of your API definition. This is only used for legacy rdme CLI workflows and only applies if your project, and this API definition, predates ReadMe Refactored. We consider this value to be deprecated and recommend against relying on it going forward.',
},
source: {
type: 'object',
properties: {
current: {
type: 'string',
enum: [
'api',
'apidesigner',
'apieditor',
'bidi',
'form',
'postman',
'rdme',
'rdme_github',
'url',
],
},
original: {
type: 'string',
enum: [
'api',
'apidesigner',
'apieditor',
'bidi',
'form',
'postman',
'rdme',
'rdme_github',
'url',
],
},
},
required: ['current', 'original'],
additionalProperties: false,
description: 'The sources by which this API definition was ingested.',
},
type: {
type: 'string',
enum: ['openapi', 'postman', 'swagger', 'unknown'],
description: 'The type of API definition. This will be `unknown` if the API definition has either not yet been processed or failed with validation errors.',
},
updated_at: {
type: 'string',
format: 'date-time',
description: 'An ISO 8601 formatted date for when the API definition was last updated.',
},
upload: {
type: 'object',
properties: {
status: {
type: 'string',
enum: ['pending', 'failed', 'done', 'pending_update', 'failed_update'],
description: 'The status of the API definition upload.',
},
reason: {
type: 'string',
nullable: true,
description: 'The reason for the upload failure if it failed.',
},
warnings: {
type: 'string',
nullable: true,
description: 'Any fixable warnings that may exist within the API definition if the upload was ingested without errors.',
},
},
required: ['status', 'reason', 'warnings'],
additionalProperties: false,
},
uri: {
type: 'string',
pattern: '\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/apis\\/((([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml)))',
description: 'A URI to the API definition resource.',
},
},
required: [
'created_at',
'filename',
'legacy_id',
'source',
'type',
'updated_at',
'upload',
'uri',
],
additionalProperties: false,
},
},
},
required: ['total', 'data'],
additionalProperties: false,
},
},
},
},
},
},
post: {
operationId: 'createAPI',
summary: 'Create an API definition',
tags: ['APIs'],
description: "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 documentation 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': {
schema: {
type: 'object',
properties: {
schema: { description: 'The API definition.' },
upload_source: {
default: 'form',
description: 'The source that the API definition is being uploaded through.',
},
url: { description: 'The URL where the API definition is hosted.' },
},
additionalProperties: false,
},
},
},
},
parameters: [
{
schema: {
type: 'string',
pattern: '(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?',
},
in: 'path',
name: 'branch',
required: true,
description: "Project version number, `stable` for your project's stable version, or a valid branch name.",
},
],
responses: {
'202': {
description: 'Accepted',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
data: {
type: 'object',
properties: {
upload: {
type: 'object',
properties: {
status: {
type: 'string',
enum: ['pending', 'failed', 'done', 'pending_update', 'failed_update'],
description: 'The status of the API definition upload.',
},
},
required: ['status'],
additionalProperties: false,
},
uri: {
type: 'string',
pattern: '\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/apis\\/((([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml)))',
description: 'A URI to the API definition resource.',
},
},
required: ['upload', 'uri'],
additionalProperties: false,
},
},
required: ['data'],
additionalProperties: false,
},
},
},
},
},
},
},
'/branches/{branch}/apis/{filename}': {
get: {
operationId: 'getAPI',
summary: 'Get an API definition',
tags: ['APIs'],
description: "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 documentation 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: '(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?',
},
in: 'path',
name: 'branch',
required: true,
description: "Project version number, `stable` for your project's stable version, or a valid branch name.",
},
],
responses: {
'200': {
description: 'OK',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
data: {
type: 'object',
properties: {
created_at: {
type: 'string',
format: 'date-time',
description: 'An ISO 8601 formatted date for when the API definition was created.',
},
filename: {
type: 'string',
description: 'This is the unique identifier, its filename, for the API definition.',
},
legacy_id: {
type: 'string',
pattern: '[a-f\\d]{24}',
nullable: true,
description: 'The legacy ID of your API definition. This is only used for legacy rdme CLI workflows and only applies if your project, and this API definition, predates ReadMe Refactored. We consider this value to be deprecated and recommend against relying on it going forward.',
},
source: {
type: 'object',
properties: {
current: {
type: 'string',
enum: [
'api',
'apidesigner',
'apieditor',
'bidi',
'form',
'postman',
'rdme',
'rdme_github',
'url',
],
},
original: {
type: 'string',
enum: [
'api',
'apidesigner',
'apieditor',
'bidi',
'form',
'postman',
'rdme',
'rdme_github',
'url',
],
},
},
required: ['current', 'original'],
additionalProperties: false,
description: 'The sources by which this API definition was ingested.',
},
type: {
type: 'string',
enum: ['openapi', 'postman', 'swagger', 'unknown'],
description: 'The type of API definition. This will be `unknown` if the API definition has either not yet been processed or failed with validation errors.',
},
updated_at: {
type: 'string',
format: 'date-time',
description: 'An ISO 8601 formatted date for when the API definition was last updated.',
},
upload: {
type: 'object',
properties: {
status: {
type: 'string',
enum: ['pending', 'failed', 'done', 'pending_update', 'failed_update'],
description: 'The status of the API definition upload.',
},
reason: {
type: 'string',
nullable: true,
description: 'The reason for the upload failure if it failed.',
},
warnings: {
type: 'string',
nullable: true,
description: 'Any fixable warnings that may exist within the API definition if the upload was ingested without errors.',
},
},
required: ['status', 'reason', 'warnings'],
additionalProperties: false,
},
uri: {
type: 'string',
pattern: '\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/apis\\/((([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml)))',
description: 'A URI to the API definition resource.',
},
schema: { type: 'object', additionalProperties: {}, description: 'The API schema.' },
},
required: [
'created_at',
'filename',
'legacy_id',
'source',
'type',
'updated_at',
'upload',
'uri',
],
additionalProperties: false,
},
},
required: ['data'],
additionalProperties: false,
},
},
},
},
},
},
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 documentation 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: '(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?',
},
in: 'path',
name: 'branch',
required: true,
description: "Project version number, `stable` for your project's stable version, or a valid branch name.",
},
],
responses: { '204': { description: 'No Content' } },
},
put: {
operationId: 'updateAPI',
summary: 'Update an API definition',
tags: ['APIs'],
description: "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 documentation 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': {
schema: {
type: 'object',
properties: {
schema: { description: 'The API definition.' },
upload_source: {
default: 'form',
description: 'The source that the API definition is being uploaded through.',
},
url: { description: 'The URL where the API definition is hosted.' },
},
additionalProperties: false,
},
},
},
},