// This file generates the MDX content for a single operation or type (a single MDX file). // The content is placed inside the `

` tag by writeMdxFile. const { isObjectType, isScalarType, isEnumType, isUnionType, isInputObjectType, isInterfaceType, } = require('graphql'); const { cleanDescription, parseMetadata, shouldHideField, getPlanInfo, formatPlanRequirements, } = require('../utils/schema-parser'); const { formatType, getUnderlyingType, isFieldRequired, getTypeLinkUrl, } = require('../utils/type-utils'); const { isDeprecated, getDeprecationReason } = require('../utils/deprecation-utils'); const { generateExpandableMdx } = require('./static-mdx-generator'); const BUILT_IN_TYPES = ['String', 'Int', 'Float', 'Boolean', 'ID']; /** * Generate plan requirement info section for an operation. * @param {Object} operation - The GraphQL operation object. * @param {Object} planInstances - Map of plan instances parsed from schema. * @returns {string} MDX content with Info component if plan requirements exist, empty string otherwise. */ function generatePlanRequirementInfo(operation, planInstances) { if (!planInstances) { return ''; } const planInfo = getPlanInfo(operation.name, planInstances); if (!planInfo) { return ''; } const planRequirements = formatPlanRequirements(planInfo); if (!planRequirements) { return ''; } return ` This endpoint requires a ${planRequirements}. [Learn more](https://dashboard.codex.io/plan). `; } /** * Generate deprecation warning section for an operation. * @param {Object} operation - The GraphQL operation object. * @param {string} operationType - The type of operation ('Query', 'Mutation', or 'Subscription'). * @returns {string} MDX content with Warning component if deprecated, empty string otherwise. */ function generateDeprecationWarning(operation, operationType) { if (!isDeprecated(operation)) { return ''; } return ` This ${operationType.toLowerCase()} is deprecated. ${cleanDescription(getDeprecationReason(operation))} `; } /** * Determine if a GraphQL type is expandable (can be rendered with nested static MDX content). * @param {Object} type - The GraphQL type object. * @param {Object} expandableTypeMap - Map of expandable types for the operation. * @returns {boolean} True if the type is expandable, false otherwise. */ function isTypeExpandable(type, expandableTypeMap) { if (!expandableTypeMap || !type || !type.name) { return false; } return ( expandableTypeMap[type.name] && (isObjectType(type) || isInputObjectType(type) || isInterfaceType(type) || isEnumType(type) || isUnionType(type)) ); } /** * Determine the rendering strategy for a GraphQL type (expandable/built-in). * @param {Object} graphqlType - The GraphQL type object. * @param {Object} typeCategories - Categorized types (unused, kept for API compatibility). * @param {Object} expandableTypeMap - Map of expandable types for the operation. * @returns {Object} Strategy object with typeName, cleanTypeName, underlyingType, isExpandable, isUnion, isInterface, and required. */ function getTypeRenderingStrategy(graphqlType, typeCategories, expandableTypeMap) { const typeName = formatType(graphqlType); const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const underlyingType = getUnderlyingType(graphqlType); const isExpandable = isTypeExpandable(underlyingType, expandableTypeMap); const isUnion = underlyingType && isUnionType(underlyingType); const isInterface = underlyingType && isInterfaceType(underlyingType); return { typeName, cleanTypeName, underlyingType, isExpandable, isUnion, isInterface, required: isFieldRequired(graphqlType), }; } /** * Generate the Returns section for an operation documentation page. * @param {Object} operation - The GraphQL operation object. * @param {Object} typeCategories - Categorized types (unused, kept for API compatibility). * @param {Object} expandableTypeMap - Map of expandable types for the operation. * @returns {string} MDX content for the Returns section. */ function generateReturnsSection(operation, typeCategories, expandableTypeMap) { const returnType = operation.type; const strategy = getTypeRenderingStrategy(returnType, typeCategories, expandableTypeMap); const { typeName, underlyingType, isExpandable, isUnion, isInterface, required } = strategy; let content = `### Returns\n\n`; if (isExpandable && expandableTypeMap) { const post = isUnion ? ['union'] : isInterface ? ['interface'] : null; const mdxContent = generateExpandableMdx(expandableTypeMap, underlyingType.name, new Set(), { fieldName: underlyingType.name, fieldType: typeName, required, description: null, deprecated: false, deprecatedReason: null, post, indentLevel: 0, typeCategories, }); content += mdxContent; } else { // Use empty string for name since Returns section has no field name const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const typeHref = getTypeLinkUrl(cleanTypeName, typeCategories); const hrefAttr = typeHref ? ` href="${typeHref}"` : ''; content += ` `; } return content; } /** * Generate the Arguments section for an operation documentation page. * @param {Object} operation - The GraphQL operation object. * @param {Object} typeCategories - Categorized types (unused, kept for API compatibility). * @param {Object} expandableTypeMap - Map of expandable types for the operation. * @returns {string} MDX content for the Arguments section, or empty string if no arguments. */ function generateArgumentsSection(operation, typeCategories, expandableTypeMap) { if (!operation.args || operation.args.length === 0) { return ''; } const visibleArgs = operation.args.filter((arg) => !shouldHideField(arg)); if (visibleArgs.length === 0) { return ''; } let content = `### Arguments\n\n`; visibleArgs.forEach((arg) => { const argDescription = cleanDescription(arg.description); const isDeprecatedArg = isDeprecated(arg); const deprecationReason = isDeprecatedArg ? cleanDescription(getDeprecationReason(arg)) : null; const strategy = getTypeRenderingStrategy(arg.type, typeCategories, expandableTypeMap); const { typeName, underlyingType, isExpandable, isUnion, isInterface, required } = strategy; if (isExpandable && expandableTypeMap) { const post = isUnion ? ['union'] : isInterface ? ['interface'] : null; const mdxContent = generateExpandableMdx(expandableTypeMap, underlyingType.name, new Set(), { fieldName: arg.name, fieldType: typeName, required, description: argDescription, deprecated: isDeprecatedArg, deprecatedReason: deprecationReason, post, indentLevel: 0, typeCategories, }); content += mdxContent; } else { const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const typeHref = getTypeLinkUrl(cleanTypeName, typeCategories); const hrefAttr = typeHref ? ` href="${typeHref}"` : ''; content += ``; if (argDescription) { content += `\n ${argDescription}`; } if (isDeprecatedArg) { content += `\n \n \n This argument is deprecated. ${deprecationReason}\n `; } content += `\n `; } }); return content; } /** * Generate documentation for a query/mutation/subscription operation. * @param {Object} operation - The GraphQL operation object. * @param {string} operationType - The type of operation ('Query', 'Mutation', or 'Subscription'). * @param {Object} [typeCategories=null] - Categorized types (unused, kept for API compatibility). * @param {Object} [planInstances=null] - Map of plan instances parsed from schema. * @param {Object} [expandableTypeMap=null] - Map of expandable types for the operation. * @returns {Object} Object with content (MDX string), metadata, title, and description. */ function generateOperationDoc( operation, operationType, typeCategories = null, planInstances = null, expandableTypeMap = null ) { const description = cleanDescription(operation.description); const metadata = parseMetadata(operation.description); // Generate only the content (no frontmatter) - frontmatter will be handled by writeMdxFile let content = ''; // Add plan requirement info if available content += generatePlanRequirementInfo(operation, planInstances); // Add deprecation warning for the operation if deprecated content += generateDeprecationWarning(operation, operationType); // Add Returns section content += generateReturnsSection(operation, typeCategories, expandableTypeMap); // Add Arguments section content += generateArgumentsSection(operation, typeCategories, expandableTypeMap); return { content: content.trim(), metadata, title: operation.name, description: description || `${operationType} operation`, }; } /** * Generate individual type documentation page content. * @param {Object} type - The GraphQL type object. * @param {Object} [typeCategories=null] - Categorized types (unused, kept for API compatibility). * @param {Object} [expandableTypeMap=null] - Map of expandable types for the type. * @returns {string} MDX content for the type documentation page. */ function generateIndividualTypeDoc(type, typeCategories = null, expandableTypeMap = null) { // Generate only the content (no frontmatter) - frontmatter will be handled by writeMdxFile let content = ''; // Add deprecation warning for the type itself if deprecated if (isDeprecated(type)) { content += ` This type is deprecated. ${cleanDescription(getDeprecationReason(type))} `; } if (isObjectType(type) || isInputObjectType(type) || isInterfaceType(type)) { const fields = Object.values(type.getFields()); const visibleFields = fields.filter((field) => !shouldHideField(field)); // Separate deprecated and non-deprecated fields const nonDeprecatedFields = visibleFields.filter((field) => !isDeprecated(field)); const deprecatedFields = visibleFields.filter((field) => isDeprecated(field)); // Render non-deprecated fields first if (nonDeprecatedFields.length > 0) { nonDeprecatedFields.forEach((field) => { const fieldDescription = cleanDescription(field.description); const strategy = getTypeRenderingStrategy(field.type, typeCategories, expandableTypeMap); const { typeName, underlyingType, isExpandable, isUnion, isInterface, required } = strategy; if (isExpandable && expandableTypeMap) { // Generate static MDX for expandable type const post = isUnion ? ['union'] : isInterface ? ['interface'] : null; const mdxContent = generateExpandableMdx( expandableTypeMap, underlyingType.name, new Set(), { fieldName: field.name, fieldType: typeName, required, description: fieldDescription, deprecated: false, deprecatedReason: null, post, indentLevel: 0, typeCategories, } ); content += mdxContent; } else { // Built-in type or non-expandable type const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const typeHref = getTypeLinkUrl(cleanTypeName, typeCategories); const hrefAttr = typeHref ? ` href="${typeHref}"` : ''; content += ``; if (fieldDescription) { content += `\n ${fieldDescription}`; } content += `\n `; } }); } // Render deprecated fields flat at the bottom (before Schema) if (deprecatedFields.length > 0) { deprecatedFields.forEach((field) => { const fieldDescription = cleanDescription(field.description); const strategy = getTypeRenderingStrategy(field.type, typeCategories, expandableTypeMap); const { typeName, underlyingType, isExpandable, isUnion, isInterface, required } = strategy; if (isExpandable && expandableTypeMap) { // Generate static MDX for expandable type const post = isUnion ? ['union'] : isInterface ? ['interface'] : null; const deprecationReason = cleanDescription(getDeprecationReason(field)); const mdxContent = generateExpandableMdx( expandableTypeMap, underlyingType.name, new Set(), { fieldName: field.name, fieldType: typeName, required, description: fieldDescription, deprecated: true, deprecatedReason: deprecationReason, post, indentLevel: 0, typeCategories, } ); content += mdxContent; } else { // Built-in type or non-expandable type const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const typeHref = getTypeLinkUrl(cleanTypeName, typeCategories); const hrefAttr = typeHref ? ` href="${typeHref}"` : ''; content += ``; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; content += `\n `; } }); } } else if (isEnumType(type)) { const values = type.getValues().filter((value) => !shouldHideField(value)); // Separate deprecated and non-deprecated enum values const nonDeprecatedValues = values.filter((value) => !isDeprecated(value)); const deprecatedValues = values.filter((value) => isDeprecated(value)); // Render non-deprecated values first if (nonDeprecatedValues.length > 0) { nonDeprecatedValues.forEach((value) => { const valueDescription = cleanDescription(value.description); content += ``; if (valueDescription) { content += `\n ${valueDescription}`; } content += `\n `; }); } // Render deprecated values flat at the bottom if (deprecatedValues.length > 0) { deprecatedValues.forEach((value) => { const valueDescription = cleanDescription(value.description); content += ``; if (valueDescription) { content += `\n ${valueDescription}`; } // Add deprecation warning for the enum value content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(value))}\n `; content += `\n `; }); } } else if (isUnionType(type)) { const unionTypes = type.getTypes(); content += `This union can be one of the following types:\n\n`; unionTypes.forEach((unionType) => { content += `- ${unionType.name}\n`; }); content += `\n`; } else if (isScalarType(type)) { // Scalars don't have fields or values, just the schema definition // Content already has description if available } return content.trim(); } module.exports = { generateOperationDoc, generateIndividualTypeDoc, };

API Documentation

Queries

Mutations

Subscriptions

Types

​Returns

​Arguments

Returns

Arguments