tessl/npm-microsoft-azure--autorest-core

AutoRest core module that generates client libraries for accessing RESTful web services from OpenAPI specifications.

—

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

Document Processing

Name: tessl/npm-microsoft-azure--autorest-core
Author: tessl

AutoRest Core provides comprehensive document type identification and format detection capabilities for OpenAPI specifications and configuration files. This enables automatic processing of various document formats and types in the code generation pipeline.

Capabilities

Document Type Identification

Identifies the type and format of documents for proper processing.

/**
 * Identifies the type of a document based on its content
 * @param content - The document content to analyze
 * @returns Promise resolving to the detected document type
 */
function IdentifyDocument(content: string): Promise<DocumentType>;

/**
 * Converts literate configuration content to JSON format
 * @param content - The literate content to convert
 * @returns Promise resolving to JSON string
 */
function LiterateToJson(content: string): Promise<string>;

/**
 * Determines if content represents a configuration document
 * @param content - The document content to check
 * @returns Promise resolving to true if it's a configuration document
 */
function IsConfigurationDocument(content: string): Promise<boolean>;

/**
 * Determines if content represents an OpenAPI document
 * @param content - The document content to check  
 * @returns Promise resolving to true if it's an OpenAPI document
 */
function IsOpenApiDocument(content: string): Promise<boolean>;

/**
 * Checks if a file extension indicates a configuration file
 * @param extension - The file extension to check (including dot)
 * @returns Promise resolving to true if it's a configuration extension
 */
function IsConfigurationExtension(extension: string): Promise<boolean>;

/**
 * Checks if a file extension indicates an OpenAPI specification file
 * @param extension - The file extension to check (including dot)
 * @returns Promise resolving to true if it's an OpenAPI extension
 */
function IsOpenApiExtension(extension: string): Promise<boolean>;

Usage Examples:

import { 
  IdentifyDocument, 
  IsOpenApiDocument, 
  IsConfigurationDocument,
  IsOpenApiExtension,
  LiterateToJson 
} from "@microsoft.azure/autorest-core";

// Identify document type from content
const swaggerContent = `{
  "swagger": "2.0",
  "info": { "title": "My API", "version": "1.0" }
}`;

const docType = await IdentifyDocument(swaggerContent);
console.log("Document type:", docType); // DocumentType.OpenAPI2

// Check if content is OpenAPI
const isOpenApi = await IsOpenApiDocument(swaggerContent);
console.log("Is OpenAPI:", isOpenApi); // true

// Check configuration document
const configContent = `{
  "input-file": "swagger.json",
  "output-folder": "./generated"
}`;

const isConfig = await IsConfigurationDocument(configContent);
console.log("Is configuration:", isConfig); // true

// Check file extensions
const isSwaggerExt = await IsOpenApiExtension(".json");
console.log("Is OpenAPI extension:", isSwaggerExt); // true

const isConfigExt = await IsConfigurationExtension(".autorest.json");
console.log("Is config extension:", isConfigExt); // true

// Convert literate config to JSON
const literateConfig = `
# AutoRest Configuration

> Input file
input-file: swagger.json

> Output settings  
output-folder: ./generated
namespace: MyClient
`;

const jsonConfig = await LiterateToJson(literateConfig);
console.log("JSON config:", jsonConfig);

Document Types

Enumeration of supported document types that AutoRest can process.

/**
 * Supported document types
 */
enum DocumentType {
  /** OpenAPI 2.0 (Swagger) specification */
  OpenAPI2 = "OpenAPI2",
  /** OpenAPI 3.0+ specification */
  OpenAPI3 = "OpenAPI3",
  /** Literate configuration document */
  LiterateConfiguration = "LiterateConfiguration", 
  /** Unknown or unsupported document type */
  Unknown = "Unknown"
}

Document Formats

Enumeration of supported document formats for parsing and processing.

/**
 * Supported document formats
 */
enum DocumentFormat {
  /** Markdown format */
  Markdown = "Markdown",
  /** YAML format */
  Yaml = "Yaml", 
  /** JSON format */
  Json = "Json",
  /** Unknown or unsupported format */
  Unknown = "Unknown"
}

File Extensions and Patterns

Constants defining file extension mappings and patterns for document recognition.

/**
 * File extension mappings for different document types
 */
const DocumentExtension: {
  [key: string]: DocumentFormat;
};

/**
 * File pattern mappings for document recognition  
 */
const DocumentPatterns: {
  [key: string]: RegExp;
};

Usage Examples:

import { 
  DocumentType, 
  DocumentFormat, 
  DocumentExtension, 
  DocumentPatterns 
} from "@microsoft.azure/autorest-core";

// Check document types
switch (docType) {
  case DocumentType.OpenAPI2:
    console.log("Processing Swagger 2.0 specification");
    break;
  case DocumentType.OpenAPI3:
    console.log("Processing OpenAPI 3.0+ specification");
    break;
  case DocumentType.LiterateConfiguration:
    console.log("Processing literate configuration");
    break;
  case DocumentType.Unknown:
    console.log("Unknown document type");
    break;
}

// Check document formats  
const format = DocumentExtension[".yaml"];
if (format === DocumentFormat.Yaml) {
  console.log("YAML format detected");
}

// Use patterns for content detection
const jsonPattern = DocumentPatterns["json"];
if (jsonPattern.test(content)) {
  console.log("Content matches JSON pattern");
}

Document Processing Pipeline

The document processing system integrates with the main AutoRest pipeline to handle various input formats:

File Discovery: Use file extensions to identify potential specification files
Content Analysis: Read file content and identify document type
Format Detection: Determine if the document is JSON, YAML, or Markdown
Type Classification: Classify as OpenAPI specification or configuration
Content Transformation: Convert literate configurations to JSON if needed
Validation: Validate document structure and content
Pipeline Integration: Pass processed documents to the generation pipeline

Supported File Extensions

OpenAPI Specifications:

.json - JSON format OpenAPI specs
.yaml, .yml - YAML format OpenAPI specs
.swagger.json - Swagger-specific JSON files
.swagger.yaml - Swagger-specific YAML files

Configuration Files:

.autorest.json - AutoRest JSON configuration
.autorest.yaml - AutoRest YAML configuration
.autorest.md - AutoRest literate configuration
README.md - Markdown configuration files

Content Detection

The document processing system uses multiple techniques for accurate identification:

JSON Schema Validation: Checks for OpenAPI schema markers
Property Detection: Looks for specific properties like swagger, openapi, info
Structure Analysis: Analyzes document structure patterns
Extension Mapping: Uses file extensions as hints for document type
Content Parsing: Parses YAML/JSON content for type-specific properties