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
  2. Installing the new parser (as described in respective readme section)
  3. 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 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.

Migrating the code

Consider this code which uses raml-java-parser:

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:

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 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

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

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 tutorial.

Need Assistance?

Here are the things to do if you have more questions:

results matching ""

    No results matching ""