raml-org / raml-js-parser-2

(deprecated)

DEPRECATION NOTICE: please note that this parser is now deprecated, please use webapi-parser instead.

—-

RAML 1.0 JS Parser

See http://raml.org for more information about RAML.

This parser supports both RAML 0.8 and 1.0.

Quick start

Install the parser: npm install raml-1-parser

Create new file test.js with the following code:

var raml = require("raml-1-parser");
var apiJSON = raml.load(ramlFileName);
console.log(JSON.stringify(apiJSON, null, 2));

where ramlFileName is a path to RAML file.

Run the test: node ./test.js

Installation

npm install raml-1-parser

node node_modules/raml-1-parser/test/test01.js  //synchronously loads XKCD API from local file system and prints its JSON representation
node node_modules/raml-1-parser/test/testAsync01.js  //asynchronously loads XKCD API from local file system and prints its JSON representation
node node_modules/raml-1-parser/test/test02.js  //synchronously loads XKCD API from github and prints its JSON representation
node node_modules/raml-1-parser/test/testAsync02.js  //asynchronously loads XKCD API from github and prints its JSON representation

Usage

• For parser usage example refer to node_modules/raml-1-parser/test/test01.js
• For asynchrounous usage example refer to node_modules/raml-1-parser/test/testAsync01.js

Parser documentation: https://raml-org.github.io/raml-js-parser-2/

Parser JSON output schema: https://github.com/raml-org/raml-js-parser-2/blob/master/tckJsonSchema/tckJsonSchema.json

Getting started guide: https://github.com/raml-org/raml-js-parser-2/blob/master/documentation/GettingStarted.md

High-level usage example: https://github.com/raml-org/raml-js-parser-2/blob/master/examples/highlevel-AST-usage/tutorial.md

Validation plugins usage example: https://github.com/raml-org/raml-js-parser-2/blob/master/examples/validationPlugins

Creating standalone browser package

Clone repository: git clone https://github.com/raml-org/raml-js-parser-2.git

Install modules: npm install

Build : npm run build

Generate browser package: npm run generateBrowserVersion, this will generate the package in browserVersion folder.

To generate debug-friendly browser package: npm run generateBrowserVersionDev

Setting up parser development environment

Clone repositories:

• git clone https://github.com/mulesoft-labs/yaml-ast-parser.git
• git clone https://github.com/mulesoft-labs/ts-model.git
• git clone https://github.com/mulesoft-labs/ts-structure-parser.git
• git clone https://github.com/raml-org/raml-typesystem.git
• git clone https://github.com/raml-org/raml-definition-system.git
• git clone https://github.com/raml-org/raml-js-parser-2.git

For each repository, preserving the order:

• Install modules: npm install
• Set up npm link: npm link

For each repository, preserving the order:

• Open dependencies: cd node_modules
• For each module <module_name> in node_modules belonging to the list above: rm -rf <module_name>
• For each module <module_name> in node_modules belonging to the list above: npm link <module_name>

For each repository, preserving the order:

• Build : npm run build

How to test: gulp test

Launching TCK tests

Execute npm run tck in the commend line. The script clones the master branch of the TCK repository to the TCK subfolder of the project and executes all the tests. The report file is TCK/report.json.

Contributing

If you are interested in contributing some code to this project, thanks! Please first read and accept the Contributors Agreement.

To discuss this project, please use its github issues or the RAML forum.

raml-js-parser-2's Issues

Publish on NPM

I would like to be able to use the RAML 1.0 parser as a dependency of my projects, can this be published on NPM?

The code includes an entire implementation of Buffer

This shouldn't be there. This is an entire native API, and probably why the parser is so huge.

Error parsing markdown starting with an html tag

Hi, I have some documentation content where the first line starts with an html tag. The parser then throws an error. If I stick a letter in-front of the tag all works again.

#%RAML 1.0 DocumentationItem

title: Data API
content: |
  <center>
  ![Black Swan Logo](images/logo_name_bottom.png)
  </center>

{ code: 7,
  message: 'String is expected documentation/index.raml',
  path: null,
  start: 164,
  end: 188,
  line: 10,
  column: 13,
  range: 
   [ { line: 10, column: 13, position: 164 },
     { line: 10, column: 37, position: 188 } ],
  isWarning: true }

Parser should fail if two security schemes have the same name

This RAML should fail with the new parser:

#%RAML 0.8
title: some API
securitySchemes:
  - scheme1:
      type: x-custom
  - scheme1:
      type: x-custom

Parser error interpretation

This RAML:

#%RAML 0.8

---
title: API 1
...
title: API 2

Produces 3 errors in the Workbench:

but the parser returns only one:

{
  "code": 1,
  "message": "JS-YAML: can not read an implicit mapping pair; a colon is missed at line 3, column 1",
  "path": null,
  "start": 28,
  "end": 29,
  "isWarning": false
}

Why are the two other errors not returned?
How should start and end be interpreted?

What version of Javascript / Node does this project support?

I don't see anything listed in package.json or elsewhere...

Option to create JSON output in the same structure as the 0.8 parser

The parser for RAML 0.8 parser produces a JavaScript object that has a different structure than the RAML file itself. E.g. resources are grouped in an "resources" property.

The new parser should have an option to produce the same format, e.g. for compatibility with raml2html

parsing returns null

Parsing this RAML and this RAML return null

Body type inheritance support

Currently when parsing a method request body or a response body, it appears that the body object does not inherit properties or examples or from the parent type.

Given the following example:

#%RAML 1.0
title: Pet shop
version: 1
baseUri: /shop

types:
  Pet:
    properties:
      name: string
      kind: string
      price: number
    example:
      name: "Snoopy"
      kind: "Mammal"
      price: 100
/pets:
  /{id}:
    get:
    reponses:
      200:
        body:
          application/json:
            type: Pet

When we run this RAML through through the parser and try to retrieve the body for the response. We get an error.

api.resources()[0].resources()[0].methods()[0].responses()[0].body()[0].properties();

TypeError: api.resources(...)[0].resources(...)[0].methods(...)[0].responses(...)[0].body(...)[0].properties is not a function

Ideally the parser should return the properties and example(s) from the parent type.

Is this feature currently on the roadmap?

Where is the unbundled source?

TraitRef must have better helpers

Right now we have to jump to High-level in order to obtain resource trait appliance parameters, trait name could also be directly provided from TraitRef method.

Typescript dependency

This package is missing in the package.json directory.

RAML should not be a global variable

From test.js

require('../src/bundle');
var RAML = global.RAML;

Array in "example" has only half of elements

Hi,
After the last update I found out that boolean arrays in "example" part have only halt of elements.
For example, I have the description:

example:
aesOutput1:
[ true, false, false, false ]
aesOutput2:
[ false, true, false, false ]

and when I try to output them by toString() I have:

true,false
false,true

Although in the previous version of raml-js-parser-2 I had four elements for each array.

Can't differentiate between integer and number when looking at runtimeType

Error scenario:

types:
Foo:
properties:
bar: integer[]

typeDeclaration.runtimeType().componentType() for Foo returns NumberType when bar is both number[] and integer[]

Put the documentation on `gh-pages`

I'm not sure how I can read the documentation directory without having to clone it and read it locally. It would be nice if it was available on gh-pages so I could read it online.

Add toJSON methods on nodes

Adding toJSON methods on the nodes would ease some of the navigation of the ast.

Status codes have strange prefix in generated JSON

All status codes (200, 400, etc.) are prefixed with __$EscapedKey$__ in the generated JSON. Why is that needed? Can it be removed?

Example:

var api = RAML.loadApi(apiPath).getOrElse(null);
var apiJSON = RAML.toJSON(api);
console.log(apiJSON);

Result (fragment):

"errorCodes": {
        "responses": {
          "__$EscapedKey$__400": {
            "description": "Bad Request.",

Array type

Hi,
Is it OK that

response.body()[0].type() is SysManagementTypes.Channel[]

but

response.body()[0].definition().allSuperTypes()[0] is String[]

?

BTW, How can I get access to properties/examples of properties of type from response.body()[idx] ?

For example, I have response body type SysManagementTypes.Channel which have some properties:

    properties:
      id: number
      name: string
      protocol: ChannelProtocol
      ipAddress: IpAddress
      port: number
      status: ChannelStatus
    example:
      id: 1
      name: Sample Channel
      protocol: Udp
      ipAddress: 192.168.218.109
      port: 2077
      status: Playing

and I can get this type by response.body()[0].type(). But I need to iterate all properties of the Channel type. How to do that?

And what if body type is Channel[] (an array)?

Can't find type name for ArrayTypeDeclaration imported from library

Example:

uses:
  AnimalLibrary: !include Animals.raml

types:
  Zoo:
   type: object
   properties:
     animal: AnimalLibrary.Animal
     animals: AnimalLibrary.Animal[]

---

For the animal property of type Zoo (ObjectTypeDeclaration):
typeDeclaration.runtimeType().superTypes[0].nameId() returns "Animal", (which is GOOD)

However, for the animals property of type Zoo (ArrayTypeDeclaration):
typeDeclaration.runtimeType().componentType().superTypes[0].nameId() returns "ValueType"
and
typeDeclaration.runtimeType().componentType().nameId() returns "StringType"

How do I figure out the type for the property animals? Things seem to work fine if the Animal type isn't defined in a library. Is this a bug, or am I doing something wrong?

Invalid error in expanded RAML

In expanded version of

resourceTypes: 
  - base:
      get:
        responses:
          200:
            body:
              schema: get-<<resourcePathName>> # e.g. get-machines

the line

schema: get-<<resourcePathName>> # e.g. get-machines

contains error:

Error: when parsingError: Syntax error:Expected "|" or end of input but "<" found.

Support reserved parameters in traits and resource types expander.

Moved from the old repo.

ResourceTypeRef must have better helpers

Right now we have to jump to High-level in order to obtain resource type appliance parameters, type name could also be directly provided from ResourceTypeRef method.

There's a bunch of module paths in the code

"modulePath": "c:\\GIT-repos\\api-workbench\\src\\raml1\\spec-1.0\\api.ts"

Parser should return the protocol(s) specified at the baseUri if the protocols property is not defined

As defined in the 1.0 spec:

The OPTIONAL protocols property specifies the protocols that an API supports. If the protocols property is not explicitly included, the protocol(s) specified at the baseUri property is (are) used

What methods are available on the `RAML` global object?

test

Create Getting Started guide for JS parser

Code includes replication of `process`

Similar to #52, I found a reimplementation of process in the codebase.

map type expression not supported

When trying to use map type expression, as stated here
I get "Syntax error:Expected "|" or end of input but "{" found.

Example:

#%RAML 1.0
title: My Api
/maps:
    get:
      responses:
        200:
          body:
            type: number{}

RAML.loadApi should be asynchronous

Parsing a RAML can be a heavy load operation, so it makes sense to make the operation asynchronous. It's also a good practice to do it using Promises.

How to help?

Hi,

I noticed that there were a few issues with the help wanted tag. How do i go about this?

It appears as though the source code for this project is held elsewhere and a compiled version is committed into this project. Is that correct?

Keen to help get RAML 1.0 parsers to a point where I can use them in my daily work.

Annotations

Hi, I'm unclear how to get info about my annotations. I have annotations on my methods. I just want to know how to get the annotation name and value.

raml

annotationTypes:
  handler:
    parameters:
      value: string

  /clients:
    get:
      (handler): routes.resources.clients.list

ast

[ AnnotationRefImpl {
    attr: 
     ASTPropImpl {
       _node: [Object],
       _parent: [Object],
       _implicit: false,
       values: {},
       _def: [Object],
       _prop: [Object],
       fromKey: false } } ]

Cleanup dependencies

It seems that some of the dependencies make no sense for this package (for example, typescript). Please check which ones are actually used and remove the rest.

Thanks!

Add support to parse RAML API fromt text instead of using a file path

Currently, the only way to use the parser is to do:

var apiFilePath = 'api.raml';
var api = RAML.loadApi(apiFilePath).getOrElse(null);

There should be a way to pass the RAML text directly, for example:

var ramlText = '#%RAML 0.8\ntitle: Anypoint Exchange';
var api = RAML.loadApiText(ramlText).getOrElse(null);

getting media types of post bodies

/login:
  description: Redirect to accounts api login
  get:
    (handler):
      path: 'login.page'
  post:
    (handler):
      path: 'login.post'
    body:
      application/json:
        type: object
        properties:
          username: string
          password: string
      application/x-www-form-urlencoded:
        type: object
        properties:
          username: string
          password: string

I can't find any way to get the post body media types. From a method node I can get bodies but that is just the object definitions underneath the media types.

Parsing a file that includes a remote file with relative includes fails

With this RAML:

#%RAML 0.8
!include https://raw.githubusercontent.com/raml-apis/XKCD/production/api.raml

the parser fails (the relative includes in api.raml are not resolved correctly) and errors cannot be traversed

api.errors().forEach(function(x){

produces this error:

TypeError: Cannot read property 'position' of null
    at /Users/juan/Projects/raml-js-parser-2/src/raml1Parser.js:9059:35
    at Array.forEach (native)
    at ASTNodeImpl.BasicASTNode.validate (/Users/juan/Projects/raml-js-parser-2/src/raml1Parser.js:9054:39)
    at ASTNodeImpl.validate (/Users/juan/Projects/raml-js-parser-2/src/raml1Parser.js:9953:40)
    at ASTNodeImpl.BasicASTNode.errors (/Users/juan/Projects/raml-js-parser-2/src/raml1Parser.js:9035:15)
    at ApiImpl.BasicNodeImpl.errors (/Users/juan/Projects/raml-js-parser-2/src/raml1Parser.js:28337:44)
    at /Users/juan/Projects/raml-js-parser-2/test/testAsync01.js:8:9
    at runMicrotasksCallback (node.js:337:7)
    at process._tickCallback (node.js:355:11)
    at Function.Module.runMain (module.js:503:11)

Generate documentation for Parser API

Throws an error when "extensions and overlays" are undefined

            throw new Error("Extensions and overlays list should be defined");
            ^

Error: Extensions and overlays list should be defined
    at Object.loadApiAsync (/Users/blakeembrey/Projects/mulesoft-labs/raml-generator/node_modules/raml-1-parser/src/raml1Parser.js:27600:16)
    at Object.loadApi (/Users/blakeembrey/Projects/mulesoft-labs/raml-generator/node_modules/raml-1-parser/src/raml1Parser.js:4147:23)
    at Object.loadApi (/Users/blakeembrey/Projects/mulesoft-labs/raml-generator/node_modules/raml-1-parser/src/raml1Parser.js:54:25)
    at Object.bin (/Users/blakeembrey/Projects/mulesoft-labs/raml-generator/dist/bin.js:28:28)
    at Object.<anonymous> (/Users/blakeembrey/Projects/mulesoft-labs/raml-javascript-generator/dist/bin.js:4:7)
    at Module._compile (module.js:399:26)
    at Object.Module._extensions..js (module.js:406:10)
    at Module.load (module.js:345:32)
    at Function.Module._load (module.js:302:12)
    at Function.Module.runMain (module.js:431:10)
    at startup (node.js:141:18)
    at node.js:977:3

The second argument is undefined.

Why convert a collection of objects to an object with numeric keys?

RAML parser parses this structure:

resourceTypes:
    - readOnlyCollection:
          description: Collection of available <<resourcePathName>> in Jukebox.
          get:
          ⋮
    - collection:
          description: Collection of available <<resourcePathName>> in Jukebox.
          get:
          ⋮

to this:

{
    resourceTypes:  {
        '0': { readOnlyCollection: [Object] },
        '1': { collection: [Object] },
        '2': { 'collection-item': [Object] }
    }
}

instead of this:

{
    resourceTypes:  [
        { readOnlyCollection: [Object] },
        { collection: [Object] },
        { 'collection-item': [Object] }
    ]
}

Why?

Parser Async should reject the Promise when parsing errors are found

Right now, the promise is fulfilled, returning an invalid API representation and clients must call the errors() method to know if there was an error.

How to change "__$EscapedKey$__" prefix?

License is wrong

According to the package.json, it says it's ISC. According to license.txt, it's Apache-2.0.

Api.expand() not working with modules

var api = ramlParser.loadApiSync('api.raml', [ 'module1.raml', 'module2.raml' ]);
api.resources().forEach(function(resource) {
        console.log('Adding resource: ' + resource.displayName());
});

This logs all resources in module1 and module2.

But when I add the api.expand(), it only logs resources in module2.

var api = ramlParser.loadApiSync('api.raml', [ 'module1.raml', 'module2.raml' ]);
api.expand().resources().forEach(function(resource) {
        console.log('Adding resource: ' + resource.displayName());
});

Did I misinterpret the expand function?

Add an example of usage of the parser in the browser

The available examples show the usage of the parser in a node like environment. Can you add an example of how to include and use the parser in a web application? Thanks!

RAML with duplicated type in Security Scheme fails in Workbench but not in the Parser

This RAML:

#%RAML 0.8
title: some API
securitySchemes:
 - scheme1:
     type: x-custom
     type: x-custom-2

In Workbench:

The parser returns:

{
  "title": "some API",
  "securitySchemes": [
    {
      "scheme1": {
        "type": "x-custom"
      }
    }
  ]
}

And errors() returns an empty array

fsResolver being called for includes with URLs

When parsing a RAML in the filesystem that includes a remote file using a URL, and providing a fsResolver and httpResolver, the fsResolver is being called for the included URL instead of the httpResolver.

Add support for modularization

Add support for Overlays and Extensions. Need to be able to handle multiple RAML files, so it probably won't fit in the current API. Perhaps the loadApi(...) and loadApiAsync(...) methods could be overloaded to accept arrays of paths in addition to single paths?

I opened a PR #29 with a test using the modularization examples from the spec. See also discussion on the forum: http://forums.raml.org/t/how-to-include-an-extension-typed-fragment.

Parsing inexisting file could throw or return a "readable" error

Sorry if this is not the place to "ask a question / make a suggestion" like that.

I have tried the following really useless code:

'use strict';
var raml = require( 'raml-1-0-parser' );
try
{
   var foo = raml.loadApi( './file-that-does-not-exists.file' );
   console.log( foo );
}
catch( e )
{
   console.log( e );
}

Although I realize the code is not realistic, the error (mistyping a file path) is. I wanted to know what happens in this situation while trying to determine the error behavior of raml-js-parser-2 to use it in another project.

The result I have had is that null is returned in foo and printed to the console. No error is thrown and nothing to indicate the source of the error.

If this is normal behavior, I would like to suggest that it should not be. Wouldn't it be possible to throw an error saying that the file does not exist.

TypeError: node.highLevel is not a function

I get this error when trying to parse this API:

C:\desarrollo\mulesoft\raml-dotnet-parser-raml1-bundle\Raml.Parser.Tester\bin\De
bug\node_modules\raml-1-0-parser\src\bundle.js:75
            return json2lowlevel.serialize(node.highLevel().lowLevel(), serializ
eOptions);
                                                ^
TypeError: node.highLevel is not a function
    at Object.toJSON (C:\desarrollo\mulesoft\raml-dotnet-parser-raml1-bundle\Ram
l.Parser.Tester\bin\Debug\node_modules\raml-1-0-parser\src\bundle.js:75:42)
    at Object.<anonymous> (C:\desarrollo\mulesoft\raml-dotnet-parser-raml1-bundl
e\Raml.Parser.Tester\bin\Debug\test.js:16:18)
    at Module._compile (module.js:434:26)
    at Object.Module._extensions..js (module.js:452:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:475:10)
    at startup (node.js:117:18)
    at node.js:951:3