Merge pull request #71 from raml-org/i52_migration_guides

Fixes #52: Add old-new parser migration guides

README.md

@@ -22,6 +22,8 @@ This project is a thin wrapper that exposes API Spec-related capabilities from [
 * [Constructing a "WebApi" Model](https://raml-org.github.io/webapi-parser/constructing.html)
 * [Translating RAML DataTypes to JSON Schemas](https://raml-org.github.io/webapi-parser/translating-raml-json.html)
 * [Translating JSON Schemas to RAML DataTypes](https://raml-org.github.io/webapi-parser/translating-json-raml.html)
+* [Migration guide (JS)](https://raml-org.github.io/webapi-parser/migration-guide-js.html)
+* [Migration guide (Java)](https://raml-org.github.io/webapi-parser/migration-guide-java.html)
 * [More examples](./examples)
 
 ## 🛠 Installation

docs/SUMMARY.md

@@ -6,3 +6,5 @@
 * [Constructing a "WebApi" Model](constructing.md)
 * [Translating RAML DataTypes to JSON Schemas](translating-raml-json.md)
 * [Translating JSON Schemas to RAML DataTypes](translating-json-raml.md)
+* [Migration guide (JS)](migration-guide-js.md)
+* [Migration guide (Java)](migration-guide-java.md)

docs/migration-guide-java.md

@@ -0,0 +1,168 @@
+---
+---
+
+# Migration guide (Java)
+Welcome!
+
+As you may already know RAML 0.8/1.0 Java parser `raml-java-parser` has been deprecated in favor of `webapi-parser`. This guide describes how to migrate an existing code from `raml-java-parser` to `webapi-parser`.
+
+Migration process consists of following steps:
+1. [Considering parsers differences](#considering-parsers-differences)
+2. Installing the new parser (as described in respective [readme section](https://github.com/raml-org/webapi-parser#java))
+3. [Migrating the code](#migrating-the-code)
+
+## Considering parsers differences
+There are few differences to consider when migrating to `webapi-parser`:
+* In addition to RAML 0.8 and RAML 1.0 parsing it can also resolve (flatten) it and validate. The parser also supports a number of other API Spec formats: OAS 2.0, OAS 3.0, AMF JSON-LD;
+* `webapi-parser` provides only async/Promise-based API;
+* API of the model/object it produces on parsing is completely different from the one produced by `raml-java-parser`. You can research the new model API by following the link in the [assistance section](#need-assistance) below.
+* When using resource types, traits, data types and other means of reusing patterns, old parser used to "flatten" these abstractions into a parsed document, making it possible to navigate and inspect them after parsing. E.g. if a resource uses a resourceType which defines a `200` response you could navigate to that response from the resource via parsed model and inspect it immediately after parsing. To achieve this behaviour in the new parser one would have to parse AND perform a [model resolution](resolving.md).
+
+## Migrating the code
+Consider this code which uses `raml-java-parser`:
+```java
+package co.acme.parse;
+
+import org.raml.v2.api.RamlModelBuilder;
+import org.raml.v2.api.RamlModelResult;
+import org.raml.v2.api.model.common.ValidationResult;
+import org.raml.v2.api.model.v10.api.Api;
+
+public class Raml10Parsing {
+  public static void parse() throws InterruptedException {
+    RamlModelResult ramlModelResult = new RamlModelBuilder().buildApi(input);
+    if (ramlModelResult.hasErrors()) {
+      for (ValidationResult validationResult : ramlModelResult.getValidationResults()) {
+        System.out.println(validationResult.getMessage());
+      }
+    } else {
+      Api api = ramlModelResult.getApiV10();
+    }
+  }
+}
+```
+
+Here's how it can be reworked to use `webapi-parser`:
+```java
+package co.acme.parse;
+
+import webapi.Raml10;
+import webapi.WebApiBaseUnit;
+import webapi.WebApiDocument;
+import amf.client.validate.ValidationReport;
+import amf.client.validate.ValidationResult;
+
+import java.util.concurrent.ExecutionException;
+
+public class Raml10Parsing {
+  public static void parse() throws InterruptedException, ExecutionException {
+    WebApiBaseUnit ramlModelResult = Raml10.parse(input).get();
+    ValidationReport validationReport = Raml10.validate(ramlModelResult).get();
+    if (!validationReport.conforms()) {
+      for (ValidationResult validationResult : validationReport.results()) {
+        System.out.println(validationResult.message());
+      }
+    } else {
+      WebApiDocument document = (WebApiDocument) ramlModelResult;
+    }
+  }
+}
+```
+
+In the example above, namespace `webapi` contains namespaces for all the supported API Spec formats: `Raml10`. `Raml08`, `Oas20`, `Oas30`, `AmfGraph`, each having an identical interface (OAS namespaces have an extra few methods). The list of supported operations each format supports includes parsing, resolution(flattening), validation and string generation.
+
+To get a description of each namespace and operation please research the new model API by following the link in the [assistance section](#need-assistance) below.
+
+## Detailed migration examples
+This section lists migration examples of the most common `raml-java-parser` parsing and model methods. Snippets are separated with a newline. First line of each example shows `raml-java-parser` method usage, while the second line shows how to achieve the same functionality with `webapi-parser` if possible. If no obvious alternative exists, a comment gives more detail.
+
+### Parsers
+```java
+import org.raml.v2.api.RamlModelBuilder;
+import webapi.Raml10;
+
+// Create a model from File instance
+new RamlModelBuilder().buildApi(ramlFile);
+// Not supported
+
+// Create a model from Reader instance and a RAML file location (String)
+new RamlModelBuilder().buildApi(reader, ramlLocation);
+// Not supported
+
+// Create a model by parsing a RAML file at a particular location
+new RamlModelBuilder().buildApi(ramlLocation);
+Raml10.parse(ramlLocation).get();
+Raml08.parse(ramlLocation).get();
+
+// Create a model by parsing RAML content string and assigning it a
+// custom location
+new RamlModelBuilder().buildApi(content, ramlLocation);
+Raml10.parse(content, ramlLocation).get();
+Raml08.parse(content, ramlLocation).get();
+```
+
+### API Models
+```java
+import org.raml.v2.api.RamlModelResult;
+import org.raml.v2.api.model.v10.api.Api;
+import webapi;
+
+// Extract 0.8 Api/WebApi instance from a parsed model
+Api oldModel = new RamlModelBuilder().buildApi(input).getApiV08();
+webapi.WebApiDocument newModel = (webapi.WebApiDocument) Raml08.parse(input).get();
+
+// Extract 1.0 Api/WebApi instance from a parsed model
+Api oldModel = new RamlModelBuilder().buildApi(input).getApiV10();
+webapi.WebApiDocument newModel = (webapi.WebApiDocument) Raml10.parse(input).get();
+
+// Parse RAML content or file path
+RamlModelResult oldResult = new RamlModelBuilder().buildApi(input);
+webapi.WebApiBaseUnit newResult = (webapi.WebApiBaseUnit) Raml10.parse(input).get();
+
+// Check if parsed model has errors
+oldResult.hasErrors();
+// Validation must be performed. See example above.
+
+// Get parsed model validation results
+oldResult.getValidationResults();
+// Validation must be performed. See example above.
+
+// Convert parsed model to a Library to use its specific interface
+oldResult.getLibrary();
+(webapi.WebApiModule) newResult;
+
+// Convert parsed model to a DataType fragment to use its specific interface
+oldResult.getTypeDeclaration();
+(webapi.WebApiDataType) newResult;
+
+// Convert parsed model to a SecurityScheme fragment to use its specific interface
+oldResult.getSecurityScheme();
+(webapi.WebApiSecuritySchemeFragment) newResult;
+
+// Convert parsed model to a Trait fragment to use its specific interface
+oldResult.getTrait();
+(webapi.WebApiTraitFragment) newResult;
+
+// Convert parsed model to a ResourceType fragment to use its specific interface
+oldResult.getResourceType();
+(webapi.WebApiResourceTypeFragment) newResult;
+
+// Get API resources/endpoints
+oldModel.resources();
+newModel.encodes().endPoints();
+// Note that webapi-parser resources are flat and occur in the order defined in the RAML doc.
+
+// Get methods of a first resource
+oldModel.resources().get(0).methods();
+newModel.encodes().endPoints().get(0).operations();
+```
+
+For more details on navigating the new model, please refer to [Navigating a "WebApi" Model](navigating.md) tutorial.
+
+
+## Need Assistance?
+Here are the things to do if you have more questions:
+* Check out more of our [tutorials](SUMMARY.md)
+* Explore relevant [examples](https://github.com/raml-org/webapi-parser/tree/master/examples/java)
+* Research the API with the [developer documentation](https://raml-org.github.io/webapi-parser/java/index.html)
+* Ask your question at [github issues](https://github.com/raml-org/webapi-parser/issues)

docs/migration-guide-js.md

@@ -0,0 +1,156 @@
+---
+---
+
+# Migration guide (JS)
+Welcome!
+
+As you may already know RAML 0.8/1.0 JS parser `raml-1-parser` has been deprecated in favor of `webapi-parser`. This guide describes how to migrate an existing code from `raml-1-parser` to `webapi-parser`.
+
+Migration process consists of following steps:
+1. [Considering parsers differences](#considering-parsers-differences)
+2. Installing the new parser (as described in respective [readme section](https://github.com/raml-org/webapi-parser#javascript))
+3. [Migrating the code](#migrating-the-code)
+
+## Considering parsers differences
+There are few differences to consider when migrating to `webapi-parser`:
+* In addition to RAML 0.8 and RAML 1.0 parsing it can also resolve (flatten) it and validate. The parser also supports a number of other API Spec formats: OAS 2.0, OAS 3.0, AMF JSON-LD;
+* `webapi-parser` provides only async/Promise-based API;
+* API of the model/object it produces on parsing is completely different from the one produced by `raml-1-parser`. You can research the new model API by following the link in the [assistance section](#need-assistance) below.
+
+## Migrating the code
+Consider this code which uses `raml-1-parser`:
+```js
+const parser = require('raml-1-parser')
+
+async someFunc () {
+  const api = await parser.loadRAML('/path/to/raml10/api.raml')
+  const expanded = api.expand(true)
+  // Do something with the expanded API
+}
+
+someFunc()
+```
+
+Here's how it can be reworked to use `webapi-parser`:
+```js
+const wap = require('webapi-parser').WebApiParser
+
+async someFunc () {
+  // Or wap.raml08 for RAML 0.8 operations
+  const api = await wap.raml10.parse('file:///path/to/raml10/api.raml')
+  const expanded = await wap.raml10.resolve(api)
+  // Do something with the expanded API
+}
+
+someFunc()
+```
+
+In the example above, object `WebApiParser` contains namespaces for all the supported API Spec formats: `raml10`. `raml08`, `oas20`, `oas30`, `amfGraph`, each having an identical interface (OAS namespaces have an extra few methods). The list of supported operations each format supports includes parsing, resolution(flattening), validation and string generation.
+
+To get a description of each namespace and operation please research the new model API by following the link in the [assistance section](#need-assistance) below.
+
+## Detailed migration examples
+This section lists migration examples of the most common `raml-1-parser` parsing and model methods. Snippets are separated with a newline. First line of each example shows `raml-1-parser` method usage, while the second line shows how to achieve the same functionality with `webapi-parser` if possible. If no obvious alternative exists, a comment gives more detail.
+
+### Parsers
+```js
+const oldParser = require('raml-1-parser')
+const wp = require('webapi-parser')
+const wap = wp.WebApiParser
+
+// Load and parse RAML file
+const node = await oldParser.loadApi('/path/to/api.raml')
+const model = await wap.raml10.parse('file:///path/to/api.raml')
+// or
+// const model = wap.raml08.parse('file:///path/to/api.raml')
+
+// Convert fragment representing node to FragmentDeclaration instance
+oldParser.asFragment(node)
+// Not necessary. Webapi-parser parses fragments into different model types.
+
+// Check if the AST node represents fragment
+oldParser.isFragment(node)
+!(model instanceof wp.webapi.WebApiDocument)
+
+// Load and parse API file synchronously
+oldParser.loadApiSync('/path/to/api.raml')
+// Not supported
+
+// Load and parse RAML file asynchronously. May load both Api and Typed fragments.
+oldParser.loadRAML('/path/to/api.raml')
+wap.raml10.parse('file:///path/to/api.raml')
+wap.raml08.parse('file:///path/to/api.raml')
+
+// Load and parse RAML file synchronously. May load both Api and Typed fragments.
+oldParser.loadRAMLSync('/path/to/api.raml')
+// Not supported
+
+// Parse RAML content asynchronously. May load both Api and Typed fragments.
+oldParser.parseRAML('#%RAML 1.0\n...')
+wap.raml10.parse('#%RAML 1.0\n...')
+wap.raml08.parse('#%RAML 1.0\n...')
+
+// Parse RAML content synchronously. May load both Api and Typed fragments.
+oldParser.parseRAMLSync('#%RAML 1.0\n...')
+// Not supported
+```
+
+### API Models
+```js
+const oldParser = require('raml-1-parser')
+const wp = require('webapi-parser')
+const wap = wp.WebApiParser
+
+// Load and parse RAML file
+const node = await oldParser.loadApi('/path/to/api.raml')
+const model = await wap.raml10.parse('file:///path/to/api.raml')
+// or
+// const model = wap.raml08.parse('file:///path/to/api.raml')
+
+// Get API resources/endpoints
+node.resources()
+model.encodes.endPoints()
+// Note that webapi-parser resources are flat and occur in the order defined in the RAML doc.
+
+// Get methods of a first API resource
+node.resources()[0].methods()
+model.encodes.endPoints()[0].operations()
+
+// Get "annotationTypes" declarations
+node.annotationTypes()
+model.declares.filter(el -> el instanceof wp.model.domain.CustomDomainProperty)
+
+// Get "resourceTypes" declarations
+node.resourceTypes()
+model.declares.filter(el -> el instanceof wp.model.domain.ParametrizedResourceType)
+
+// Get "schemas" declarations
+node.schemas()
+model.declares.filter(el -> el instanceof wp.model.domain.SchemaShape)
+
+// Get "securitySchemes" declarations
+node.securitySchemes()
+model.declares.filter(el -> el instanceof wp.model.domain.SecurityScheme)
+
+// Get "traits" declarations
+node.traits()
+model.declares.filter(el -> el instanceof wp.model.domain.ParametrizedTrait)
+
+// Get "types" declarations
+node.types()
+model.declares.filter(el -> el instanceof wp.model.domain.AnyShape)
+
+// Expand (resolve) parsed API model
+node.expand()
+wap.raml10.resolve(model)
+```
+
+For more details on navigating the new model, please refer to [Navigating a "WebApi" Model](navigating.md) tutorial.
+
+
+## Need Assistance?
+Here are the things to do if you have more questions:
+* Check out more of our [tutorials](SUMMARY.md)
+* Explore relevant [examples](https://github.com/raml-org/webapi-parser/tree/master/examples/js)
+* Research the API with the [developer documentation](https://raml-org.github.io/webapi-parser/js/modules/webapiparser.html)
+* Ask your question at [github issues](https://github.com/raml-org/webapi-parser/issues)