tessl/npm-microsoft--api-documenter

Reads API Extractor JSON files and generates API documentation in various output formats

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

YAML Type Definitions

Name: tessl/npm-microsoft--api-documenter
Author: tessl

Comprehensive type system for generating YAML documentation compatible with DocFX and Office Add-ins documentation platforms. These types define the structure and metadata for API documentation in YAML format.

Capabilities

YAML Format Types

Core format selection and configuration types.

type YamlFormat = 'udp' | 'sdp';

type YamlTypeId = 
  | 'Class'
  | 'Constructor' 
  | 'Enum'
  | 'Field'
  | 'Function'
  | 'Interface'
  | 'Method'
  | 'Namespace'
  | 'Package'
  | 'Property'
  | 'TypeAlias'
  | 'Variable';

type YamlDevLangs = 'javascript' | 'typescript' | 'nodejs';

API File Structure

Main YAML file structure for API documentation with complete metadata.

interface IYamlApiFile {
  /**
   * Array of API items documented in this file
   */
  items: IYamlItem[];
  
  /**
   * Documentation references and cross-links
   */
  references?: IYamlReference[];
  
  /**
   * File metadata and generation information
   */
  metadata?: {
    generator: string;
    generatorVersion: string;
    generatedDate: string;
  };
}

interface IYamlItem {
  /**
   * Unique identifier for this API item
   */
  uid: string;
  
  /**
   * Display name of the API item
   */
  name: string;
  
  /**
   * Full name including namespace/package context
   */
  fullName?: string;
  
  /**
   * Type of API item (Class, Method, Property, etc.)
   */
  type: YamlTypeId;
  
  /**
   * Programming language context
   */
  langs?: YamlDevLangs[];
  
  /**
   * Package or namespace containing this item
   */
  package?: string;
  
  /**
   * Summary documentation text
   */
  summary?: string;
  
  /**
   * Detailed remarks and additional documentation
   */
  remarks?: string;
  
  /**
   * Usage examples in code
   */
  example?: string;
  
  /**
   * Syntax information for this API item
   */
  syntax?: IYamlSyntax;
  
  /**
   * Inheritance hierarchy information
   */
  inheritance?: IYamlInheritanceTree[];
  
  /**
   * Child items (methods, properties, etc.)
   */
  children?: string[];
  
  /**
   * Source code location information
   */
  source?: IYamlSource;
  
  /**
   * Deprecation notice if applicable
   */
  deprecated?: IYamlDeprecatedNotice;
  
  /**
   * Exception information for methods
   */
  exceptions?: IYamlException[];
}

Syntax Information

Detailed syntax and signature information for API items.

interface IYamlSyntax {
  /**
   * Code signature or declaration
   */
  content?: string;
  
  /**
   * Parameters for functions and methods
   */
  parameters?: IYamlParameter[];
  
  /**
   * Return value information
   */
  return?: IYamlReturn;
  
  /**
   * Type parameters for generic types
   */
  typeParameters?: IYamlParameter[];
}

interface IYamlParameter {
  /**
   * Parameter identifier
   */
  id: string;
  
  /**
   * Parameter type information
   */
  type?: string;
  
  /**
   * Parameter description
   */
  description?: string;
  
  /**
   * Whether parameter is optional
   */
  optional?: boolean;
  
  /**
   * Default value if any
   */
  defaultValue?: string;
}

interface IYamlReturn {
  /**
   * Return type information
   */
  type?: string;
  
  /**
   * Description of return value
   */
  description?: string;
}

Reference and Link System

Cross-reference and linking system for API documentation.

interface IYamlReference {
  /**
   * Unique identifier for the referenced item
   */
  uid: string;
  
  /**
   * Display name of referenced item
   */
  name: string;
  
  /**
   * Full name with context
   */
  fullName?: string;
  
  /**
   * Type of referenced item
   */
  type?: YamlTypeId;
  
  /**
   * Reference specifications
   */
  spec?: IYamlReferenceSpec[];
}

interface IYamlReferenceSpec {
  /**
   * Reference UID
   */
  uid: string;
  
  /**
   * Display name in reference context
   */
  name: string;
  
  /**
   * Full qualified name
   */
  fullName?: string;
}

interface IYamlLink {
  /**
   * Link URL or reference
   */
  href?: string;
  
  /**
   * Link display text
   */
  text?: string;
  
  /**
   * Link type (external, internal, etc.)
   */
  type?: 'internal' | 'external';
}

Source Location Information

Source code location and repository information.

interface IYamlSource {
  /**
   * Source file path
   */
  path?: string;
  
  /**
   * Starting line number
   */
  startLine?: number;
  
  /**
   * Remote repository information
   */
  remote?: IYamlRemote;
}

interface IYamlRemote {
  /**
   * Repository URL
   */
  repo: string;
  
  /**
   * Branch or commit reference
   */
  branch?: string;
  
  /**
   * File path within repository
   */
  path?: string;
}

Inheritance and Type Hierarchy

Type inheritance and relationship information.

interface IYamlInheritanceTree {
  /**
   * Type information for inheritance relationship
   */
  type?: string;
  
  /**
   * Reference UID for inherited type
   */
  uid?: string;
  
  /**
   * Inheritance level (0 = direct parent)
   */
  level?: number;
}

Exception Documentation

Exception and error information for methods and functions.

interface IYamlException {
  /**
   * Exception type name
   */
  type?: string;
  
  /**
   * Exception type UID reference
   */
  uid?: string;
  
  /**
   * Description of when this exception is thrown
   */
  description?: string;
}

interface IYamlDeprecatedNotice {
  /**
   * Deprecation message
   */
  message?: string;
  
  /**
   * Version when deprecated
   */
  version?: string;
  
  /**
   * Replacement recommendation
   */
  replacement?: string;
}

Table of Contents Structure

YAML table of contents for navigation and organization.

interface IYamlTocFile {
  /**
   * Array of top-level TOC items
   */
  items?: IYamlTocItem[];
  
  /**
   * Metadata for the TOC file
   */
  metadata?: {
    tocTitle?: string;
    tocDescription?: string;
  };
}

interface IYamlTocItem {
  /**
   * Display name in table of contents
   */
  name?: string;
  
  /**
   * Reference UID for this item
   */
  uid?: string;
  
  /**
   * Direct link href (alternative to uid)
   */
  href?: string;
  
  /**
   * Child items in the hierarchy
   */
  items?: IYamlTocItem[];
  
  /**
   * Whether this item is expanded by default
   */
  expanded?: boolean;
}

SDP (Structured Data Platform) Types

Enhanced type system for the newer SDP YAML format with improved structure and metadata.

SDP Model Types

type CommonYamlModel = {
  /**
   * Unique identifier
   */
  uid: string;
  
  /**
   * Display name
   */
  name: string;
  
  /**
   * Item type
   */
  type: YamlTypeId;
  
  /**
   * Summary documentation
   */
  summary?: string;
  
  /**
   * Syntax information
   */
  syntax?: ISyntax;
  
  /**
   * Source location
   */
  source?: IYamlSource;
};

type PackageYamlModel = CommonYamlModel & {
  type: 'Package';
  /**
   * Package version
   */
  version?: string;
  
  /**
   * Package description
   */
  description?: string;
  
  /**
   * Child namespaces and classes
   */
  children?: string[];
};

type FunctionYamlModel = CommonYamlModel & {
  type: 'Function';
  /**
   * Function parameters
   */
  parameters?: IYamlParameter[];
  
  /**
   * Return type information
   */
  returns?: IYamlReturn;
  
  /**
   * Possible exceptions
   */
  exceptions?: IException[];
};

type TypeAliasYamlModel = CommonYamlModel & {
  type: 'TypeAlias';
  /**
   * Type definition
   */
  typeDefinition?: IType;
};

type EnumYamlModel = CommonYamlModel & {
  type: 'Enum';
  /**
   * Enum members
   */
  fields?: FieldYamlModel[];
};

type FieldYamlModel = CommonYamlModel & {
  type: 'Field';
  /**
   * Field value (for enum members)
   */
  value?: string | number;
};

SDP Type System

Enhanced type representation for SDP format.

interface IType {
  /**
   * Type name or identifier
   */
  name?: string;
  
  /**
   * Type kind (primitive, reference, union, etc.)
   */
  kind?: 'primitive' | 'reference' | 'union' | 'intersection' | 'generic' | 'reflected';
  
  /**
   * Type arguments for generic types
   */
  typeArguments?: IType[];
  
  /**
   * Union type members
   */
  unionTypes?: IUnionType[];
  
  /**
   * Intersection type members  
   */
  intersectionTypes?: IIntersectionType[];
}

interface IUnionType {
  /**
   * Union member type
   */
  type: IType;
  
  /**
   * Optional discriminator value
   */
  discriminator?: string;
}

interface IIntersectionType {
  /**
   * Intersection member type
   */
  type: IType;
}

interface IGenericType {
  /**
   * Generic type constraint
   */
  constraint?: IType;
  
  /**
   * Default type argument
   */
  default?: IType;
}

interface IReflectedType {
  /**
   * Reflected type structure
   */
  declaration?: {
    signatures?: ISyntax[];
    children?: IType[];
  };
}

SDP Syntax Information

Enhanced syntax representation for SDP format.

interface ISyntax {
  /**
   * Syntax content/signature
   */
  content?: string;
  
  /**
   * Parameters with enhanced type information
   */
  parameters?: IYamlParameter[];
  
  /**
   * Return type with detailed information
   */
  return?: {
    type?: IType;
    description?: string;
  };
  
  /**
   * Type parameters for generic signatures
   */
  typeParameters?: Array<{
    name: string;
    constraint?: IType;
    default?: IType;
    description?: string;
  }>;
}

interface IException {
  /**
   * Exception type
   */
  type?: IType;
  
  /**
   * Exception description
   */
  description?: string;
  
  /**
   * Conditions when thrown
   */
  condition?: string;
}

Usage Examples

Basic YAML Generation

import { IYamlApiFile, IYamlItem } from "@microsoft/api-documenter/lib/yaml/IYamlApiFile";

// Create YAML API file structure
const yamlFile: IYamlApiFile = {
  items: [
    {
      uid: "mypackage.MyClass",
      name: "MyClass", 
      type: "Class",
      langs: ["typescript"],
      package: "mypackage",
      summary: "A sample class for demonstration",
      syntax: {
        content: "class MyClass",
        parameters: []
      },
      children: ["mypackage.MyClass.method1"]
    }
  ],
  metadata: {
    generator: "api-documenter",
    generatorVersion: "7.26.32",
    generatedDate: new Date().toISOString()
  }
};

TOC Generation

import { IYamlTocFile, IYamlTocItem } from "@microsoft/api-documenter/lib/yaml/IYamlTocFile";

// Create table of contents
const tocFile: IYamlTocFile = {
  items: [
    {
      name: "API Reference",
      uid: "mypackage",
      expanded: true,
      items: [
        {
          name: "Classes",
          items: [
            {
              name: "MyClass",
              uid: "mypackage.MyClass"
            }
          ]
        }
      ]
    }
  ],
  metadata: {
    tocTitle: "My Package API",
    tocDescription: "Complete API reference for My Package"
  }
};

Format Conversion

UDP to SDP Conversion

import { convertUDPYamlToSDP } from "@microsoft/api-documenter/lib/utils/ToSdpConvertHelper";

// Convert UDP format to SDP format
const udpYaml = {
  // UDP format structure
};

const sdpYaml = convertUDPYamlToSDP(udpYaml);

This conversion utility transforms legacy UDP (Universal DocFX Platform) format YAML to the newer SDP (Structured Data Platform) format with enhanced type information and improved structure.