Registry / http-networking / webapi-parser

webapi-parser

library0.5.0jsnpmunverified

webapi-parser is a JavaScript and Java library that acts as a thin wrapper around the API Modeling Framework (AMF) to parse, validate, and navigate API specifications. It supports various formats including RAML 0.8, RAML 1.0, OpenAPI (OAS) 2.0, and OpenAPI (OAS) 3.0 (currently in beta). The current stable version is v0.5.0. The library receives updates driven primarily by new releases of the underlying AMF framework, leading to a somewhat irregular but active release cadence. Its key differentiator is its ability to uniformly process multiple API definition languages through a consistent object model, making it suitable for tooling that needs to work across different specification types.

http-networking serialization devops

npm install webapi-parser

github ↗package ↗

INSTALL

IMPORT

SIG · WEBAPI-PARSER

webapi-parser

http-networkingjavascriptv0.5.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebApiParser

✓ import { WebApiParser } from 'webapi-parser';

✗ const wap = require('webapi-parser').WebApiParser;

For CommonJS environments, the main class is `WebApiParser` exported from the top-level module. For ES Modules and TypeScript, use named import. The README shows an older CJS style `const wap = require('webapi-parser').WebApiParser` which is less precise for modern ES Modules.

WebApiParser.oas30

✓ import { WebApiParser } from 'webapi-parser'; const model = await WebApiParser.oas30.parse(oas3Spec);

OpenAPI 3.0 support was added in v0.5.0 and requires accessing the `oas30` namespace from `WebApiParser`. Parsing methods are isolated here for OAS 3.0 documents, maintaining a distinction from OAS 2.0 and RAML parsing paths.

StrField

✓ import { ScalarNode } from 'webapi-parser'; const value = scalarNode.value.value();

Since v0.3.0, methods like `ScalarNode.value` and `ScalarNode.dataType` return a `StrField` object, not a raw string. You must call `.value()` on the `StrField` to get the string, or `.option()` to get an optional string.

Parses a basic OpenAPI 3.0 specification string and demonstrates how to access its title, version, and iterate through endpoints and operations within the resulting WebApi model, including basic error checking.

import { WebApiParser } from 'webapi-parser'; async function parseOas3Spec() { const oas3Spec = ` openapi: 3.0.0 info: title: My Sample API version: 1.0.0 description: An example API demonstrating webapi-parser capabilities. paths: /hello: get: summary: Say hello responses: '200': description: A greeting message content: application/json: schema: type: object properties: message: type: string `; try { // Parse the OpenAPI 3.0 specification const model = await WebApiParser.oas30.parse(oas3Spec); console.log('API Model parsed successfully.'); const webApi = model.webApi; if (webApi) { console.log(`API Title: ${webApi.name?.value() || 'N/A'}`); console.log(`API Version: ${webApi.version?.value() || 'N/A'}`); console.log(`API Description: ${webApi.description?.value() || 'N/A'}`); webApi.endPoints.forEach(endpoint => { console.log(` Endpoint Path: ${endpoint.path?.value()}`); endpoint.operations.forEach(operation => { console.log(` Operation Method: ${operation.method?.value()}`); operation.responses.forEach(response => { console.log(` Response Status: ${response.statusCode?.value()}`); response.payloads.forEach(payload => { console.log(` Payload Media Type: ${payload.mediaType?.value()}`); }); }); }); }); const errors = model.getErrors(); if (errors && errors.length > 0) { console.error('Validation errors found after parsing:'); errors.forEach(error => console.error(`- ${error.message}`)); } else { console.log('No validation errors reported by the parser for this spec.'); } } else { console.log('No WebApi object found in the parsed model.'); } } catch (error: any) { console.error('Error parsing API specification:', error.message); } } parseOas3Spec();

Debug

Known issues

breakingThe internal Security API models for `WebApi`, `EndPoint`, and `Operation` have changed types. This is a breaking change for code interacting directly with security definitions within these objects.

fix

Review the AMF 4.0.3 release notes and webapi-parser documentation for updated security model interfaces and adjust type definitions and access patterns accordingly.

affects: >=0.5.0

gotchaOpenAPI 3.0 support was introduced as a beta feature and resides in a dedicated namespace (`WebApiParser.oas30`). Using the general `WebApiParser.parse()` method for OAS 3.0 will not work.

fix

For OpenAPI 3.0 documents, always use `WebApiParser.oas30.parse(specString)`.

affects: >=0.5.0

breakingThe `ScalarNode.value` and `ScalarNode.dataType` methods now return a `StrField` object instead of a raw `String`. Direct string operations will fail.

fix

To retrieve the string value, call `.value()` on the returned `StrField` (e.g., `scalarNode.value.value()`). For nullable values, use `.option()`.

affects: >=0.3.0

breakingUpgrading the underlying AMF library to 4.0.2 in v0.4.0 introduced changes to the JSON-LD model. While the public object model interfaces of webapi-parser were intended to remain the same, developers relying on internal AMF JSON-LD representation or advanced AMF features might experience compatibility issues.

fix

Consult the AMF 4.0.1 release notes for detailed JSON-LD changes. If you are interacting with the underlying AMF model directly, verify your code against the new structure.

affects: >=0.4.0

breakingFor Java users (and potentially advanced JavaScript users interacting with underlying AMF types), `WebApiBaseUnit.getDeclarationByName` now returns `amf.client.model.domain.AnyShape` instead of `amf.client.model.domain.NodeShape`. This is a less specific return type.

fix

Adjust type casting or type checks to handle `AnyShape`. Since `NodeShape` is a subclass of `AnyShape`, direct usage might continue to work if only `AnyShape` methods are used, but explicit casting may be required for `NodeShape`-specific functionality.

affects: >=0.2.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'parse') at WebApiParser.parse

Attempting to parse an OpenAPI 3.0 document using the general `WebApiParser.parse()` method, which is not designed for OAS 3.0.

fix

For OpenAPI 3.0 specifications, use the dedicated `WebApiParser.oas30.parse(specString)` method.

Property 'startsWith' does not exist on type 'StrField'. Did you mean 'value'?

Directly trying to use string methods (like `startsWith`, `substring`, etc.) on a `StrField` object returned by `ScalarNode.value` or `ScalarNode.dataType`.

fix

Access the underlying string value first by calling `.value()` on the `StrField` (e.g., `scalarNode.value.value().startsWith(...)`).

TypeError: WebApiParser is not a constructor (or similar 'undefined' error for WebApiParser)

Incorrect CommonJS `require` or ES module `import` syntax when trying to access the `WebApiParser` class.

fix

Ensure you are using the correct import for your environment: `import { WebApiParser } from 'webapi-parser';` for ESM/TypeScript or `const { WebApiParser } = require('webapi-parser');` for CommonJS.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/raml-org/webapi-parser ↗

packagehttps://www.npmjs.com/package/webapi-parser ↗