From 0fb6dec618366d82689f9d7d0da6f6df50e14aa5 Mon Sep 17 00:00:00 2001
From: Sergio Moya <1083296+smoya@users.noreply.github.com>
Date: Wed, 16 Feb 2022 12:01:57 +0100
Subject: [PATCH] docs: add first statements about parserjs v2 and
 intent-driven usage (#447)

---
 README.md                | 22 +++++++++++++++++++---
 API.md => docs/api/v1.md |  0
 docs/api/v2.md           |  1 +
 package.json             |  2 +-
 4 files changed, 21 insertions(+), 4 deletions(-)
 rename API.md => docs/api/v1.md (100%)
 create mode 100644 docs/api/v2.md

diff --git a/README.md b/README.md
index e5c0dd8e0..86ce22bd6 100644
--- a/README.md
+++ b/README.md
@@ -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
 
@@ -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
 
diff --git a/API.md b/docs/api/v1.md
similarity index 100%
rename from API.md
rename to docs/api/v1.md
diff --git a/docs/api/v2.md b/docs/api/v2.md
new file mode 100644
index 000000000..2fd9f9570
--- /dev/null
+++ b/docs/api/v2.md
@@ -0,0 +1 @@
+TBD
\ No newline at end of file
diff --git a/package.json b/package.json
index f599f7f71..dbcf02510 100644
--- a/package.json
+++ b/package.json
@@ -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",