SpecLynx Language Service

Intelligent editing for API specifications

SpecLynx ApiDOM Language Service (@speclynx/apidom-ls) is a language service library that provides intelligent editing capabilities for API description languages.

Key Capabilities

13 core features for API specification editing:

Supported Languages

Full support for major API specification formats in both JSON and YAML.

Validation

Detects syntax and semantic issues with detailed diagnostic reporting. Returns errors and warnings per specification rules.

const diagnostics = await languageService.doValidation(document);
// Returns: Diagnostic[] with severity, message, range

Completion

Delivers context-sensitive suggestions during editing. Includes reference completion for $ref values with path suggestions.

const completions = await languageService.doCompletion(document, position);
// Returns: CompletionList with context-aware suggestions

Hover

Shows documentation and type details when hovering over symbols. Provides markdown-formatted content from the specification.

const hover = await languageService.doHover(document, position);
// Returns: Hover with markdown documentation

Navigation

Navigate through your API specifications with definition lookup and reference finding.

Go to Definition

Jumps to $ref targets within the document.

const definition = await languageService.doProvideDefinition(document, params);
// Returns: Location of the definition

Find References

Locates all uses of a symbol across the specification.

const references = await languageService.doFindReferences(document, params);
// Returns: Location[] of all references

Document Symbols

Generates outlines and breadcrumbs for document navigation. Provides a hierarchical view of the specification structure.

const symbols = await languageService.doProvideDocumentSymbols(document);
// Returns: DocumentSymbol[] hierarchy

Semantic Tokens

Provides advanced syntax highlighting through semantic token computation. Enables context-aware coloring of API specification elements.

const tokens = await languageService.computeSemanticTokens(document);
// Returns: SemanticTokens for enhanced highlighting

Code Actions

Offers quick fixes and refactoring options based on diagnostics and cursor position.

const actions = await languageService.doCodeActions(document, params);
// Returns: CodeAction[] with quick fixes

Formatting

Standardizes document structure with consistent indentation and formatting.

const edits = await languageService.doFormat(document, options);
// Returns: TextEdit[] to apply formatting

Format Conversion

Switches between JSON and YAML formats while preserving the specification structure.

const converted = await languageService.doConvertFormat(document, targetFormat);
// Returns: Converted document content

Dereferencing

Expands all $ref references, replacing them with actual definitions.

const dereferenced = await languageService.doDeref(document);
// Returns: Fully dereferenced document

Installation

npm install @speclynx/apidom-ls

Quick Start

import { getLanguageService } from '@speclynx/apidom-ls';
import { TextDocument } from 'vscode-languageserver-textdocument';

// Create the language service
const languageService = getLanguageService({});

// Create a document from your API specification
const spec = `
openapi: "3.1.0"
info:
  title: My API
  version: 1.0.0
paths: {}
`;

const document = TextDocument.create(
  'file:///api.yaml',
  'yaml',
  0,
  spec
);

// Get validation diagnostics
const diagnostics = await languageService.doValidation(document);

// Get completions at a position
const completions = await languageService.doCompletion(document, { line: 4, character: 0 });

// Always terminate when done
languageService.terminate();

Configuration

The language service accepts configuration options for customization:

import { getLanguageService, LogLevel } from '@speclynx/apidom-ls';

const languageService = getLanguageService({
  logLevel: LogLevel.WARN,
  // Custom providers
  validatorProviders: [...],
  completionProviders: [...],
  hoverProviders: [...],
  // Link following in hover
  hoverFollowLinks: true,
});

Configuration Options

Architecture

The Language Service sits between your application and the ApiDOM parsing layer:

Support

Enterprise support is available for organizations requiring dedicated assistance.

License

Licensed under Apache 2.0.

Related Products

Frequently Asked Questions