Skip to content

Commit

Permalink
docs: add first statements about parserjs v2 and intent-driven usage (a…
Browse files Browse the repository at this point in the history
  • Loading branch information
smoya authored and magicmatatjahu committed Oct 3, 2022
1 parent 1840651 commit 0fb6dec
Show file tree
Hide file tree
Showing 4 changed files with 21 additions and 4 deletions.
22 changes: 19 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,9 +106,25 @@ Head over to [asyncapi/raml-dt-schema-parser](https://www.github.com/asyncapi/ra

## API documentation

The parser API is generally structured the same way as the AsyncAPI specification, with additional support functions such as `has<Something>()`. The parser uses wrapped functions to get the properties stored in JSON. This means in order to get the info object you would use the function `doc.info()` and to get the title inside the info object you call `doc.info().title()`.
Parser-JS API implements a global API definition for all AsyncAPI parser implementations known as the [Parser-API](https://github.com/asyncapi/parser-api).
This API is designed having in mind developer experience and resiliency to breaking changes.

See [API documentation](/API.md) for more example and full API reference information.
The following table shows a compatibility matrix between this parser, and the [Parser-API](https://github.com/asyncapi/parser-api), as well as the AsyncAPI spec version supported by each release of this parser.

Parser-JS | Parser-API | Spec 2.x | Spec 3.x
----------|----------------------------------------------------------------------|----------|---------
1.x | | ✓ |
2.x | [1.x](https://github.com/asyncapi/parser-api/blob/master/docs/v1.md) | | ✓

- `` Fully supported version.
- `-` The AsyncAPI Spec version has features the Parser-JS can't use but the rest are fully supported.
- Empty means not supported version.

Additionally to all the methods declared in the [Parser-API](https://github.com/asyncapi/parser-api), this parser might introduce some helper functions.

Direct access to the parsed JSON document is always available through the `doc.raw()` method.

See [API documentation](/docs/api/v2.md) for more example and full API reference information.

## Using in the browser

Expand Down Expand Up @@ -191,7 +207,7 @@ This package throws a bunch of different error types. All errors contain a `type
|`schema-validation-errors`| `parsedJSON`, `validationErrors` | Schema of the payload provided in the AsyncAPI document is not valid with AsyncAPI schema format.
|`fetch-url-error`| None | The URL provided for fetching AsynAPI document is invalid.
For more information about the `ParserError` class, [check out the documentation](./API.md#new_ParserError_new).
For more information about the `ParserError` class, [check out the documentation](./docs/api/v1.md#new_ParserError_new).
## Custom extensions
Expand Down
File renamed without changes.
1 change: 1 addition & 0 deletions docs/api/v2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
TBD
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"scripts": {
"test": "npm run test:browser:cleanup && npm run test:lib && npm run test:parseFromUrl && npm run cover:report && npm run test:browser",
"bundle": "browserify \"lib/browser.js\" | uglifyjs > \"dist/bundle.js\"",
"docs": "jsdoc2md \"lib/parser.js\" -f \"lib/**/*.js\" > API.md",
"docs": "jsdoc2md \"lib/parser.js\" -f \"lib/**/*.js\" > docs/api/v2.md",
"types": "jsdoc -t \"node_modules/tsd-jsdoc/dist\" -r lib -d \"./\" && node \"./scripts/fix-ts-types.js\"",
"prepublishOnly": "npm run bundle && npm run docs && npm run types",
"release": "semantic-release",
Expand Down

0 comments on commit 0fb6dec

Please sign in to comment.