{"id":14330,"library":"webapi-parser","title":"Web API Parser (webapi-parser)","description":"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.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/raml-org/webapi-parser","tags":["javascript","typescript"],"install":[{"cmd":"npm install webapi-parser","lang":"bash","label":"npm"},{"cmd":"yarn add webapi-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add webapi-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const wap = require('webapi-parser').WebApiParser;","symbol":"WebApiParser","correct":"import { WebApiParser } from 'webapi-parser';"},{"note":"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.","symbol":"WebApiParser.oas30","correct":"import { WebApiParser } from 'webapi-parser';\nconst model = await WebApiParser.oas30.parse(oas3Spec);"},{"note":"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.","symbol":"StrField","correct":"import { ScalarNode } from 'webapi-parser';\nconst value = scalarNode.value.value();"}],"quickstart":{"code":"import { WebApiParser } from 'webapi-parser';\n\nasync function parseOas3Spec() {\n  const oas3Spec = `\n    openapi: 3.0.0\n    info:\n      title: My Sample API\n      version: 1.0.0\n      description: An example API demonstrating webapi-parser capabilities.\n    paths:\n      /hello:\n        get:\n          summary: Say hello\n          responses:\n            '200':\n              description: A greeting message\n              content:\n                application/json:\n                  schema:\n                    type: object\n                    properties:\n                      message:\n                        type: string\n  `;\n\n  try {\n    // Parse the OpenAPI 3.0 specification\n    const model = await WebApiParser.oas30.parse(oas3Spec);\n    console.log('API Model parsed successfully.');\n\n    const webApi = model.webApi;\n    if (webApi) {\n      console.log(`API Title: ${webApi.name?.value() || 'N/A'}`);\n      console.log(`API Version: ${webApi.version?.value() || 'N/A'}`);\n      console.log(`API Description: ${webApi.description?.value() || 'N/A'}`);\n\n      webApi.endPoints.forEach(endpoint => {\n        console.log(`  Endpoint Path: ${endpoint.path?.value()}`);\n        endpoint.operations.forEach(operation => {\n          console.log(`    Operation Method: ${operation.method?.value()}`);\n          operation.responses.forEach(response => {\n            console.log(`      Response Status: ${response.statusCode?.value()}`);\n            response.payloads.forEach(payload => {\n              console.log(`        Payload Media Type: ${payload.mediaType?.value()}`);\n            });\n          });\n        });\n      });\n\n      const errors = model.getErrors();\n      if (errors && errors.length > 0) {\n        console.error('Validation errors found after parsing:');\n        errors.forEach(error => console.error(`- ${error.message}`));\n      } else {\n        console.log('No validation errors reported by the parser for this spec.');\n      }\n    } else {\n      console.log('No WebApi object found in the parsed model.');\n    }\n\n  } catch (error: any) {\n    console.error('Error parsing API specification:', error.message);\n  }\n}\n\nparseOas3Spec();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"For OpenAPI 3.0 documents, always use `WebApiParser.oas30.parse(specString)`.","message":"OpenAPI 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.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"To retrieve the string value, call `.value()` on the returned `StrField` (e.g., `scalarNode.value.value()`). For nullable values, use `.option()`.","message":"The `ScalarNode.value` and `ScalarNode.dataType` methods now return a `StrField` object instead of a raw `String`. Direct string operations will fail.","severity":"breaking","affected_versions":">=0.3.0"},{"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.","message":"Upgrading 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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"For 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.","severity":"breaking","affected_versions":">=0.2.0"}],"env_vars":null,"search_vec":"'0.8':41 '1.0':43 '2.0':46 '3.0':50 'abil':88 'across':110 'act':17 'activ':80 'amf':27,72 'api':2,24,33,93 'around':22 'beta':53 'cadenc':82 'consist':98 'current':51,55 'definit':94 'differ':111 'differenti':85 'driven':64 'format':38 'framework':26,73 'includ':39 'irregular':78 'java':14 'javascript':12,114 'key':84 'languag':95 'lead':74 'librari':15,61 'make':101 'model':25,100 'multipl':92 'navig':32 'need':107 'new':67 'oa':45,49 'object':99 'openapi':44,48 'pars':29 'parser':3,6,9 'primarili':65 'process':91 'raml':40,42 'receiv':62 'releas':68,81 'somewhat':77 'specif':34,112 'stabl':56 'suitabl':103 'support':36 'thin':20 'tool':105 'type':113 'typescript':115 'under':71 'uniform':90 'updat':63 'v0.5.0':59 'valid':30 'various':37 'version':57 'web':1 'webapi':5,8 'webapi-pars':4,7 'work':109 'wrapper':21","created_at":"2026-04-20T01:59:09.040028+00:00","updated_at":"2026-04-20T01:59:09.040028+00:00","problems":[{"fix":"For OpenAPI 3.0 specifications, use the dedicated `WebApiParser.oas30.parse(specString)` method.","cause":"Attempting to parse an OpenAPI 3.0 document using the general `WebApiParser.parse()` method, which is not designed for OAS 3.0.","error":"TypeError: Cannot read properties of undefined (reading 'parse') at WebApiParser.parse"},{"fix":"Access the underlying string value first by calling `.value()` on the `StrField` (e.g., `scalarNode.value.value().startsWith(...)`).","cause":"Directly trying to use string methods (like `startsWith`, `substring`, etc.) on a `StrField` object returned by `ScalarNode.value` or `ScalarNode.dataType`.","error":"Property 'startsWith' does not exist on type 'StrField'. Did you mean 'value'?"},{"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.","cause":"Incorrect CommonJS `require` or ES module `import` syntax when trying to access the `WebApiParser` class.","error":"TypeError: WebApiParser is not a constructor (or similar 'undefined' error for WebApiParser)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/raml-org/webapi-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/webapi-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}