Overview

SpecLynx ApiDOM Language Service (@speclynx/apidom-ls) is a language service library that provides intelligent editing features for API description languages. It implements programmatic language features following the Language Server Protocol (LSP) specification, making it easy to integrate into any LSP-compatible editor or IDE through a server wrapper.

Note: This is a language service, not a language server. A language service is a library that implements language features, while a language server is a separate process that communicates via LSP. This library can be wrapped by an LSP server to expose its features to editors.

Supported Languages

| Language | Versions | Formats | |----------|-----------------------------------|---------| | OpenAPI | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2 | JSON, YAML | | AsyncAPI | 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6 | JSON, YAML | | Arazzo | 1.0.0, 1.0.1 | JSON, YAML | | JSON Schema | Draft 4/5, 6, 7, 2019-09, 2020-12 | JSON, YAML |

Features

The language service provides the following LSP-compatible features:

| Feature | Method | Description | |---------|--------|-------------| | Validation | doValidation() | Syntax and semantic validation with diagnostics | | Completion | doCompletion() | Context-aware auto-completion suggestions | | Hover | doHover() | Documentation and type information on hover | | Go to Definition | doProvideDefinition() | Navigate to $ref target definitions | | Find References | doProvideReferences() | Find all references to a symbol | | Document Symbols | doFindDocumentSymbols() | Outline view and breadcrumbs | | Semantic Tokens | computeSemanticTokens() | Enhanced syntax highlighting | | Code Actions | doCodeActions() | Quick fixes and refactoring | | Document Links | doLinks() | Clickable links in documents | | Formatting | doFormatting() | Document formatting | | Dereferencing | doDeref() | Resolve all $ref references | | Format Conversion | doConversion() | Convert between JSON and YAML | | Color Support | findDocumentColors() | Color picker for color values |

Installation

npm install @speclynx/apidom-ls

Quick Start

Basic Setup

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
);

Validation

const diagnostics = await languageService.doValidation(document);

for (const diagnostic of diagnostics) {
  console.log(`[${diagnostic.severity}] Line ${diagnostic.range.start.line}: ${diagnostic.message}`);
}

Auto-Completion

import { Position } from 'vscode-languageserver-types';

const position = Position.create(4, 2); // line 4, character 2
const completions = await languageService.doCompletion(document, {
  textDocument: { uri: document.uri },
  position
});

console.log('Suggestions:', completions?.items.map(item => item.label));

Hover Information

const hover = await languageService.doHover(document, Position.create(1, 5));

if (hover) {
  console.log('Hover content:', hover.contents);
}

Go to Definition

const definition = await languageService.doProvideDefinition(document, {
  textDocument: { uri: document.uri },
  position: Position.create(10, 15) // position on a $ref value
});

if (definition) {
  console.log('Definition location:', definition.uri, definition.range);
}

Cleanup

// Always terminate when done to free resources
languageService.terminate();

Advanced Configuration

The language service can be configured with custom providers and settings:

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

const languageService = getLanguageService({
  // Logging configuration
  logLevel: LogLevel.WARN,
  performanceLogs: false,

  // Custom validation providers
  validatorProviders: [/* custom validators */],

  // Custom completion providers
  completionProviders: [/* custom completions */],

  // Custom hover providers
  hoverProviders: [/* custom hovers */],

  // Enable clickable links for URLs in hover
  hoverFollowLinkEntry: true,
});

Architecture

        ┌─────────────────────────────────────┐
        │          Your Application           │
        │      (IDE, Editor, CLI, etc.)       │
        └─────────────────┬───────────────────┘
                          │
                          ▼
        ┌─────────────────────────────────────┐
        │         LSP Server Wrapper          │
        │      (implements LSP protocol)      │
        └─────────────────┬───────────────────┘
                          │
                          ▼
  ╔═══════════════════════════════════════════════╗
  ║                                               ║
  ║       SpecLynx ApiDOM Language Service        ║
  ║            (this language service)            ║
  ║                                               ║
  ╚═══════════════════════╤═══════════════════════╝
                          │
                          ▼
        ┌─────────────────────────────────────┐
        │           SpecLynx ApiDOM           │
        │   parsing ∙ datamodel ∙ traversal   │
        └─────────────────────────────────────┘

Support & Documentation

For full documentation and enterprise support please contact: [email protected]

License

ApiDOM Language Service is licensed under Apache 2.0 license. ApiDOM Language Service comes with an explicit NOTICE file inside npm distribution package containing additional legal notices and information.

This project uses REUSE specification that defines a standardized method for declaring copyright and licensing for software projects.