resolveOpenAPI.ts

/* eslint import/no-nodejs-modules:0 */

import {promises as fs} from 'fs';

import {DeRefedOpenAPI, Parameter} from './open-api/types';

// SENTRY_API_SCHEMA_SHA is used in the sentry-docs GHA workflow in getsentry/sentry-api-schema.
// DO NOT change variable name unless you change it in the sentry-docs GHA workflow in getsentry/sentry-api-schema.
const SENTRY_API_SCHEMA_SHA = '969e159ee8ff0111f82d155cbd60aa2f4b1d6d99';

const activeEnv = process.env.GATSBY_ENV || process.env.NODE_ENV || 'development';

async function resolveOpenAPI(): Promise<DeRefedOpenAPI> {
  if (activeEnv === 'development' && process.env.OPENAPI_LOCAL_PATH) {
    try {
      console.log(`Fetching from ${process.env.OPENAPI_LOCAL_PATH}`);
      const data = await fs.readFile(process.env.OPENAPI_LOCAL_PATH, 'utf8');
      return JSON.parse(data);
    } catch (error) {
      console.log(
        `Failed to connect to  ${process.env.OPENAPI_LOCAL_PATH}. Continuing to fetch versioned schema from GitHub.
        ${error}`
      );
    }
  }
  const response = await fetch(
    `https://raw.githubusercontent.com/getsentry/sentry-api-schema/${SENTRY_API_SCHEMA_SHA}/openapi-derefed.json`
  );
  return await response.json();
}

export type APIParameter = {
  description: string;
  experimental: boolean;
  name: string;
  required: boolean;
  schema: {
    type: string;
    enum?: string[];
    format?: string;
    items?: {
      type: string;
      enum?: string[];
    };
  };
};

type APIExample = {
  summary: string;
  value: any;
};

type APIResponse = {
  description: string;
  status_code: string;
  content?: {
    content_type: string;
    schema: any;
    example?: APIExample;
    examples?: {[key: string]: APIExample};
  };
};

type APIData = DeRefedOpenAPI['paths'][string][string];

export type API = {
  apiPath: string;
  bodyParameters: APIParameter[];
  deprecated: boolean;
  experimental: boolean;
  method: string;
  name: string;
  pathParameters: APIParameter[];
  queryParameters: APIParameter[];
  responses: APIResponse[];
  server: string;
  slug: string;
  bodyContentType?: string;
  descriptionMarkdown?: string;
  requestBodyContent?: any;
  security?: {[key: string]: string[]};
  summary?: string;
};

export type APICategory = {
  apis: API[];
  name: string;
  slug: string;

  /** description is a string of markdown with possible links */
  description?: string;
};

// Slashes become separators: an endpoint slug must be one URL segment, because the
// API route only matches /api/<category>/<endpoint>/.
function slugify(s: string): string {
  return s
    .replace(/\//g, ' ')
    .replace(/[^a-zA-Z0-9 ]/g, '')
    .trim()
    .replace(/\s/g, '-')
    .toLowerCase();
}

const DEPRECATED_PREFIX_REGEX = /^\(DEPRECATED\)\s*/;

// Sentry prepends this notice to the description of every experimental operation, so
// that consumers with no badge of their own still warn the reader. We render a badge
// and the same sentence beside it, so strip the prefix rather than saying it twice.
// Parameter notices stay in the description: the parameter badge does not repeat them.
const EXPERIMENTAL_NOTICE_REGEX = /^\*\*Experimental:\*\*[^\n]*\n+/;

type ExperimentalExtension = {
  description?: string;
  'x-sentry-experimental'?: boolean;
};

// `extensions={"x-sentry-experimental": True}` on an OpenAPI parameter or body
// property lands as a sibling vendor extension.
export function toDocumentedParameter<T extends ExperimentalExtension>(
  param: T
): T & {experimental: boolean} {
  return {
    ...param,
    experimental: param['x-sentry-experimental'] === true,
  };
}

function isDeprecatedOperationId(operationId: string | undefined): boolean {
  return operationId ? DEPRECATED_PREFIX_REGEX.test(operationId) : false;
}

function stripDeprecatedPrefix(operationId: string): string {
  return operationId.replace(DEPRECATED_PREFIX_REGEX, '');
}

let apiCategoriesCache: Promise<APICategory[]> | undefined;

export function apiCategories(): Promise<APICategory[]> {
  if (apiCategoriesCache) {
    return apiCategoriesCache;
  }
  apiCategoriesCache = apiCategoriesUncached();
  return apiCategoriesCache;
}

async function apiCategoriesUncached(): Promise<APICategory[]> {
  const data = await resolveOpenAPI();

  const categoryMap: {[name: string]: APICategory} = {};
  data.tags.forEach(tag => {
    categoryMap[tag.name] = {
      name: tag['x-sidebar-name'] || tag.name,
      slug: slugify(tag.name),
      description: tag['x-display-description'] ? tag.description : undefined,
      apis: [],
    };
  });

  Object.entries(data.paths).forEach(([apiPath, methods]) => {
    Object.entries(methods).forEach(([method, apiData]) => {
      // Detect deprecation from either field independently — the (DEPRECATED)
      // marker may sit on operationId even when a summary is present.
      const isDeprecated =
        isDeprecatedOperationId(apiData.operationId) ||
        isDeprecatedOperationId(apiData.summary);
      const isExperimental = apiData['x-sentry-experimental'] === true;
      const titleSource = apiData.summary || apiData.operationId || '';
      const cleanName = stripDeprecatedPrefix(titleSource);

      let server = 'https://sentry.io';
      if (apiData.servers && apiData.servers[0]) {
        server = apiData.servers[0].url;
      }
      apiData.tags.forEach(tag => {
        categoryMap[tag].apis.push({
          apiPath,
          method,
          name: cleanName,
          deprecated: isDeprecated,
          experimental: isExperimental,
          server,
          slug: slugify(cleanName),
          summary: apiData.summary
            ? stripDeprecatedPrefix(apiData.summary)
            : apiData.summary,
          descriptionMarkdown: isExperimental
            ? apiData.description?.replace(EXPERIMENTAL_NOTICE_REGEX, '')
            : apiData.description,
          pathParameters: documentedParameters(apiData.parameters, 'path'),
          queryParameters: documentedParameters(apiData.parameters, 'query'),
          requestBodyContent: {
            example:
              apiData.requestBody?.content &&
              Object.values(apiData.requestBody.content)[0].example,
          },
          bodyContentType: getBodyContentType(apiData),
          bodyParameters: getBodyParameters(apiData),
          security: apiData.security,
          responses: Object.entries(apiData.responses)
            .map(([status_code, response]) => ({
              status_code,
              ...response,
            }))
            .map(response => {
              const {content, ...rest} = response;
              return {
                content:
                  content &&
                  Object.entries(content).map(([content_type, contentData]) => ({
                    content_type,
                    ...contentData,
                  }))[0],
                ...rest,
              };
            }),
        });
      });
    });
  });

  const categories = Object.values(categoryMap);
  categories.sort((a, b) => a.name.localeCompare(b.name));
  categories.forEach(c => {
    c.apis.sort((a, b) => a.name.localeCompare(b.name));
  });
  return categories;
}

function documentedParameters(
  parameters: Parameter[] | undefined,
  location: 'path' | 'query'
): APIParameter[] {
  return (parameters || [])
    .filter(param => param.in === location)
    .map(param => {
      const documented = toDocumentedParameter(param);
      return {
        name: documented.name,
        description: documented.description,
        required: documented.required,
        experimental: documented.experimental,
        // OpenAPI item schemas are an open record; the page only reads type and enum.
        schema: documented.schema as APIParameter['schema'],
      };
    });
}

function getBodyParameters(apiData: APIData): APIParameter[] {
  const content = apiData.requestBody?.content;
  const contentType = content && Object.values(content)[0];
  const properties = contentType?.schema?.properties;
  if (!properties) {
    return [];
  }

  const required: string[] = contentType?.schema?.required || [];

  return Object.entries(properties).map(([name, props]: [string, any]) =>
    toDocumentedParameter({
      name,
      description: props.description,
      required: required.includes(name),
      'x-sentry-experimental': props['x-sentry-experimental'],
      schema: {
        type: props.type,
        format: '',
        items: props.items,
      },
    })
  );
}

function getBodyContentType(apiData: APIData): string | undefined {
  const content = apiData.requestBody?.content;
  const types = content && Object.keys(content);
  if (!types?.length) {
    return undefined;
  }
  return types[0];
}