From 9f968600e9f23fe6c774abc95e2500dad709db0c Mon Sep 17 00:00:00 2001 From: Artem Kostiuk Date: Tue, 2 Jun 2020 12:00:41 +0300 Subject: [PATCH 1/5] Update Gradle in Java examples --- examples/java/gradle/wrapper/gradle-wrapper.properties | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/java/gradle/wrapper/gradle-wrapper.properties b/examples/java/gradle/wrapper/gradle-wrapper.properties index d308d28..63a1c3e 100644 --- a/examples/java/gradle/wrapper/gradle-wrapper.properties +++ b/examples/java/gradle/wrapper/gradle-wrapper.properties @@ -1,4 +1,4 @@ -distributionUrl=https\://services.gradle.org/distributions/gradle-3.5-all.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-6.4.1-all.zip distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists zipStorePath=wrapper/dists From 9cfe61672a6d3926e9b73ba446b7d1866ca0459d Mon Sep 17 00:00:00 2001 From: Artem Kostiuk Date: Tue, 2 Jun 2020 12:00:57 +0300 Subject: [PATCH 2/5] Add resolution examples --- .../java/co/acme/demo/WebApiParserDemo.java | 84 ++++++++++--------- .../java/co/acme/model/Raml10Resolution.java | 22 +++++ examples/js/raml10-resolution.js | 36 ++++++++ 3 files changed, 101 insertions(+), 41 deletions(-) create mode 100644 examples/java/src/main/java/co/acme/model/Raml10Resolution.java create mode 100644 examples/js/raml10-resolution.js diff --git a/examples/java/src/main/java/co/acme/demo/WebApiParserDemo.java b/examples/java/src/main/java/co/acme/demo/WebApiParserDemo.java index 50c4d42..4718f6a 100644 --- a/examples/java/src/main/java/co/acme/demo/WebApiParserDemo.java +++ b/examples/java/src/main/java/co/acme/demo/WebApiParserDemo.java @@ -18,6 +18,7 @@ import co.acme.model.Raml10Building; import co.acme.model.Raml10Navigation; import co.acme.model.Raml10UtilityMethods; +import co.acme.model.Raml10Resolution; import co.acme.translate.RamlDtToJsonSchema; import co.acme.translate.JsonSchemaToRamlDt; @@ -27,59 +28,60 @@ // Runs all the example classes public class WebApiParserDemo { public static void main(String[] args) throws ExecutionException, InterruptedException, UnsupportedEncodingException { - Raml10Parsing.parseStringWithLocation(); - Raml10Parsing.parseString(); - Raml10Parsing.parseFile(); + // Raml10Parsing.parseStringWithLocation(); + // Raml10Parsing.parseString(); + // Raml10Parsing.parseFile(); - Raml08Parsing.parseString(); - Raml08Parsing.parseFile(); + // Raml08Parsing.parseString(); + // Raml08Parsing.parseFile(); - Oas20Parsing.parseString(); - Oas20Parsing.parseFile(); - Oas20Parsing.parseYamlString(); - Oas20Parsing.parseYamlFile(); + // Oas20Parsing.parseString(); + // Oas20Parsing.parseFile(); + // Oas20Parsing.parseYamlString(); + // Oas20Parsing.parseYamlFile(); - Oas30Parsing.parseString(); - Oas30Parsing.parseFile(); - Oas30Parsing.parseYamlString(); - Oas30Parsing.parseYamlFile(); + // Oas30Parsing.parseString(); + // Oas30Parsing.parseFile(); + // Oas30Parsing.parseYamlString(); + // Oas30Parsing.parseYamlFile(); - AmfGraphParsing.parseString(); - AmfGraphParsing.parseFile(); + // AmfGraphParsing.parseString(); + // AmfGraphParsing.parseFile(); - Raml10Generation.generateString(); - Raml10Generation.generateFile(); + // Raml10Generation.generateString(); + // Raml10Generation.generateFile(); - Raml08Generation.generateString(); - Raml08Generation.generateFile(); + // Raml08Generation.generateString(); + // Raml08Generation.generateFile(); - Oas20Generation.generateString(); - Oas20Generation.generateFile(); - Oas20Generation.generateYamlString(); - Oas20Generation.generateYamlFile(); + // Oas20Generation.generateString(); + // Oas20Generation.generateFile(); + // Oas20Generation.generateYamlString(); + // Oas20Generation.generateYamlFile(); - Oas30Generation.generateString(); - Oas30Generation.generateFile(); - Oas30Generation.generateYamlString(); - Oas30Generation.generateYamlFile(); + // Oas30Generation.generateString(); + // Oas30Generation.generateFile(); + // Oas30Generation.generateYamlString(); + // Oas30Generation.generateYamlFile(); - AmfGraphGeneration.generateString(); - AmfGraphGeneration.generateFile(); + // AmfGraphGeneration.generateString(); + // AmfGraphGeneration.generateFile(); - Raml10Validation.validate(); - Raml08Validation.validate(); - Oas20Validation.validate(); - Oas30Validation.validate(); - AmfGraphValidation.validate(); + // Raml10Validation.validate(); + // Raml08Validation.validate(); + // Oas20Validation.validate(); + // Oas30Validation.validate(); + // AmfGraphValidation.validate(); - Raml10Building.buildApi(); - Raml10Navigation.navigateApi(); - Raml10UtilityMethods.navigateApi(); + // Raml10Building.buildApi(); + // Raml10Navigation.navigateApi(); + // Raml10UtilityMethods.navigateApi(); + Raml10Resolution.resolveApi(); - RamlDtToJsonSchema.translateFromApi(); - RamlDtToJsonSchema.translateFromLibrary(); - RamlDtToJsonSchema.translateFromDataType(); + // RamlDtToJsonSchema.translateFromApi(); + // RamlDtToJsonSchema.translateFromLibrary(); + // RamlDtToJsonSchema.translateFromDataType(); - JsonSchemaToRamlDt.translateFromApi(); + // JsonSchemaToRamlDt.translateFromApi(); } } diff --git a/examples/java/src/main/java/co/acme/model/Raml10Resolution.java b/examples/java/src/main/java/co/acme/model/Raml10Resolution.java new file mode 100644 index 0000000..0e01cae --- /dev/null +++ b/examples/java/src/main/java/co/acme/model/Raml10Resolution.java @@ -0,0 +1,22 @@ +package co.acme.model; + +import webapi.Raml10; +import webapi.WebApiDocument; + +import java.util.concurrent.ExecutionException; + +public class Raml10Resolution { + + // Example of resolving RAML 1.0 file + public static void resolveApi() throws InterruptedException, ExecutionException { + // Parse the file + WebApiDocument doc = (WebApiDocument) Raml10.parse("file://../api-specs/raml/api-with-types.raml").get(); + + // Resolve parsed model + WebApiDocument resolved = (WebApiDocument) Raml10.resolve(doc).get(); + + // Generate RAML 1.0 string from the resolved model and log it + String output = Raml10.generateString(resolved).get(); + System.out.println("Generated Raml10 string:\n" + output); + } +} diff --git a/examples/js/raml10-resolution.js b/examples/js/raml10-resolution.js new file mode 100644 index 0000000..c703f69 --- /dev/null +++ b/examples/js/raml10-resolution.js @@ -0,0 +1,36 @@ +/** + * Example of resolving/expanding RAML 1.0 data types. + */ +const wap = require('webapi-parser').WebApiParser +const path = require('path') + +const ramlStr = `#%RAML 1.0 Library +types: + User: + type: object + properties: + firstName: string + lastName: string + Admin: + type: User + properties: + permissions: + type: array + items: string +` + +async function main () { + // Parse RAML 1.0 string + const model = await wap.raml10.parse(ramlStr) + + // Resolve/expand types defined in the document + const resolved = await wap.raml10.resolve(model) + + // Generate output file with the resolved model RAML content + const outPath = path.join(__dirname, './generated.raml') + await wap.raml10.generateFile(resolved, `file://${outPath}`) + // Or + // const outputRaml = await wap.raml10.generateString(resolved) +} + +main() From 4afd6a5feb7423c036717d814b92d8b7eb88b917 Mon Sep 17 00:00:00 2001 From: Artem Kostiuk Date: Tue, 2 Jun 2020 12:01:56 +0300 Subject: [PATCH 3/5] Add datatype-expansion migration doc --- docs/SUMMARY.md | 5 +- docs/migration-guide-datatype-expansion.md | 133 +++++++++++++++++++++ docs/migration-guide-java.md | 2 +- docs/migration-guide-js.md | 2 +- 4 files changed, 138 insertions(+), 4 deletions(-) create mode 100644 docs/migration-guide-datatype-expansion.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index c024921..8eb2b82 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -6,5 +6,6 @@ * [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) +* [Migration guide (raml-1-parser, JS)](migration-guide-js.md) +* [Migration guide (raml-java-parser, Java)](migration-guide-java.md) +* [Migration guide (datatype-expansion)](migration-guide-datatype-expansion.md) diff --git a/docs/migration-guide-datatype-expansion.md b/docs/migration-guide-datatype-expansion.md new file mode 100644 index 0000000..6089e64 --- /dev/null +++ b/docs/migration-guide-datatype-expansion.md @@ -0,0 +1,133 @@ +--- +--- + +# Migration guide (datatype-expansion) +Welcome! + +As you may already know RAML JS tool `datatype-expansion` has been deprecated. This guide describes a similar functionality offered by `webapi-parser`, thus allowing to migrate from `datatype-expansion` to `webapi-parser`. + +## datatype-expansion and webapi-parser +While `datatype-expansion` is a utility tool to expand a given type and create a canonical form, `webapi-parser` is an API Spec parser which currently supports RAML 0.8, RAML 1.0, OAS 2.0 and OAS 3.0(beta). + +Among other `webapi-parser` functionality is an API/process called "resolution". This process is performed by syntax-specific `.resolve()` methods of all supported API syntaxes (RAML, OAS, AMF Graph). + +Resolving produces a "flat" document/model with all the references replaced by redundant copies of an actual data, thus replacing functionality offered by `datatype-expansion`. `webapi-parser` can resolve RAML APIs and all the supported fragments (Library, DataType, etc.). + +For more details or resolution process, please see the [Resolving a "WebApi" Model](https://raml-org.github.io/webapi-parser/resolving.html) document. + +## Installing webapi-parser +To install `webapi-parser` follow guidelines from the respective [readme section](https://github.com/raml-org/webapi-parser#javascript). + +## Example project +### Files + +`input.raml` +```yaml +#%RAML 1.0 Library +types: + User: + type: object + properties: + firstName: string + lastName: string + Admin: + type: User + properties: + permissions: + type: array + items: string +``` + +`index.js` +```js +const wap = require('webapi-parser').WebApiParser +const path = require('path') + +async function main () { + // Step 1 + const inputPath = path.join(__dirname, 'input.raml') + const model = await wap.raml10.parse(`file://${inputPath}`) + + // Step 2 + const resolved = await wap.raml10.resolve(model) + + // Step 3 + const outPath = path.join(__dirname, './output.raml') + await wap.raml10.generateFile(resolved, `file://${outPath}`) +} + +main() +``` + +`output.raml` +```yaml +#%RAML 1.0 Library +types: + User: + type: object + additionalProperties: true + properties: + firstName: + type: string + required: true + lastName: + type: string + required: true + Admin: + type: object + additionalProperties: true + properties: + firstName: + type: string + required: true + lastName: + type: string + required: true + permissions: + type: array + items: + type: string + required: true +``` + +### Explanation +Now considering the input (`input.raml`) let's describe contents of `index.js` line-by-line. + +First all the necessary modules are imported. This includes `webapi-parser` namespace `WebApiParser` which contains most of the lib's public API: +```js +const wap = require('webapi-parser').WebApiParser +const path = require('path') +``` + +Then the input file `input.raml` is parsed by calling the `.parse()` method from the `raml10` namespace. Input of the method can be either file path or a RAML string. Parsing produces a ["WebApi" Model](https://raml-org.github.io/webapi-parser/js/classes/webapibaseunit.html): +```js + const inputPath = path.join(__dirname, 'input.raml') + const model = await wap.raml10.parse(`file://${inputPath}`) +``` + +Next line is where the magic happens. By calling the `.resolve()` method parsed model is "resolved", producing a "resolved"/expanded model: +```js + const resolved = await wap.raml10.resolve(model) +``` + +To conclude our processing we generate output RAML file (`output.raml`) from the resolved model: +```js + const outPath = path.join(__dirname, './output.raml') + await wap.raml10.generateFile(resolved, `file://${outPath}`) +``` + +We could also generate a RAML string instead of the file by calling: +```js + const ramlString = wap.raml10.generateString(resolved) +``` + +Feel free to inspect contents of the `output.raml` file above and note how types definitions and their inheritance was flattened/expanded. + +Note that "WebApi" Model functionality isn't limited to output generation. It can also be inspected and altered in JS and Java code and converter to other API spec formats (OAS2.0, OAS 3.0, etc.). + +## 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) diff --git a/docs/migration-guide-java.md b/docs/migration-guide-java.md index 0b7da56..0d43abf 100644 --- a/docs/migration-guide-java.md +++ b/docs/migration-guide-java.md @@ -1,7 +1,7 @@ --- --- -# Migration guide (Java) +# Migration guide (raml-java-parser, 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`. diff --git a/docs/migration-guide-js.md b/docs/migration-guide-js.md index f199036..ccd668d 100644 --- a/docs/migration-guide-js.md +++ b/docs/migration-guide-js.md @@ -1,7 +1,7 @@ --- --- -# Migration guide (JS) +# Migration guide (raml-1-parser, 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`. From 1a7898873141b9bb0ea9dd8935169279201e5eb4 Mon Sep 17 00:00:00 2001 From: Artem Kostiuk Date: Tue, 2 Jun 2020 12:18:35 +0300 Subject: [PATCH 4/5] Uncomment Java examples --- .../java/co/acme/demo/WebApiParserDemo.java | 104 +++++++++--------- 1 file changed, 52 insertions(+), 52 deletions(-) diff --git a/examples/java/src/main/java/co/acme/demo/WebApiParserDemo.java b/examples/java/src/main/java/co/acme/demo/WebApiParserDemo.java index 4718f6a..e47d4d5 100644 --- a/examples/java/src/main/java/co/acme/demo/WebApiParserDemo.java +++ b/examples/java/src/main/java/co/acme/demo/WebApiParserDemo.java @@ -28,60 +28,60 @@ // Runs all the example classes public class WebApiParserDemo { public static void main(String[] args) throws ExecutionException, InterruptedException, UnsupportedEncodingException { - // Raml10Parsing.parseStringWithLocation(); - // Raml10Parsing.parseString(); - // Raml10Parsing.parseFile(); - - // Raml08Parsing.parseString(); - // Raml08Parsing.parseFile(); - - // Oas20Parsing.parseString(); - // Oas20Parsing.parseFile(); - // Oas20Parsing.parseYamlString(); - // Oas20Parsing.parseYamlFile(); - - // Oas30Parsing.parseString(); - // Oas30Parsing.parseFile(); - // Oas30Parsing.parseYamlString(); - // Oas30Parsing.parseYamlFile(); - - // AmfGraphParsing.parseString(); - // AmfGraphParsing.parseFile(); - - // Raml10Generation.generateString(); - // Raml10Generation.generateFile(); - - // Raml08Generation.generateString(); - // Raml08Generation.generateFile(); - - // Oas20Generation.generateString(); - // Oas20Generation.generateFile(); - // Oas20Generation.generateYamlString(); - // Oas20Generation.generateYamlFile(); - - // Oas30Generation.generateString(); - // Oas30Generation.generateFile(); - // Oas30Generation.generateYamlString(); - // Oas30Generation.generateYamlFile(); - - // AmfGraphGeneration.generateString(); - // AmfGraphGeneration.generateFile(); - - // Raml10Validation.validate(); - // Raml08Validation.validate(); - // Oas20Validation.validate(); - // Oas30Validation.validate(); - // AmfGraphValidation.validate(); - - // Raml10Building.buildApi(); - // Raml10Navigation.navigateApi(); - // Raml10UtilityMethods.navigateApi(); + Raml10Parsing.parseStringWithLocation(); + Raml10Parsing.parseString(); + Raml10Parsing.parseFile(); + + Raml08Parsing.parseString(); + Raml08Parsing.parseFile(); + + Oas20Parsing.parseString(); + Oas20Parsing.parseFile(); + Oas20Parsing.parseYamlString(); + Oas20Parsing.parseYamlFile(); + + Oas30Parsing.parseString(); + Oas30Parsing.parseFile(); + Oas30Parsing.parseYamlString(); + Oas30Parsing.parseYamlFile(); + + AmfGraphParsing.parseString(); + AmfGraphParsing.parseFile(); + + Raml10Generation.generateString(); + Raml10Generation.generateFile(); + + Raml08Generation.generateString(); + Raml08Generation.generateFile(); + + Oas20Generation.generateString(); + Oas20Generation.generateFile(); + Oas20Generation.generateYamlString(); + Oas20Generation.generateYamlFile(); + + Oas30Generation.generateString(); + Oas30Generation.generateFile(); + Oas30Generation.generateYamlString(); + Oas30Generation.generateYamlFile(); + + AmfGraphGeneration.generateString(); + AmfGraphGeneration.generateFile(); + + Raml10Validation.validate(); + Raml08Validation.validate(); + Oas20Validation.validate(); + Oas30Validation.validate(); + AmfGraphValidation.validate(); + + Raml10Building.buildApi(); + Raml10Navigation.navigateApi(); + Raml10UtilityMethods.navigateApi(); Raml10Resolution.resolveApi(); - // RamlDtToJsonSchema.translateFromApi(); - // RamlDtToJsonSchema.translateFromLibrary(); - // RamlDtToJsonSchema.translateFromDataType(); + RamlDtToJsonSchema.translateFromApi(); + RamlDtToJsonSchema.translateFromLibrary(); + RamlDtToJsonSchema.translateFromDataType(); - // JsonSchemaToRamlDt.translateFromApi(); + JsonSchemaToRamlDt.translateFromApi(); } } From c2fdb5ebf838997bf456414195c7b9cddf869d7a Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 15 Jun 2020 20:38:00 -0700 Subject: [PATCH 5/5] Typos --- docs/migration-guide-datatype-expansion.md | 25 +++++++++++----------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/migration-guide-datatype-expansion.md b/docs/migration-guide-datatype-expansion.md index 6089e64..d20724b 100644 --- a/docs/migration-guide-datatype-expansion.md +++ b/docs/migration-guide-datatype-expansion.md @@ -4,19 +4,19 @@ # Migration guide (datatype-expansion) Welcome! -As you may already know RAML JS tool `datatype-expansion` has been deprecated. This guide describes a similar functionality offered by `webapi-parser`, thus allowing to migrate from `datatype-expansion` to `webapi-parser`. +As you may be aware, the tool [`datatype-expansion`](https://github.com/raml-org/datatype-expansion) has been deprecated. This guide describes a similar functionality that leverages `webapi-parser`, which may help migrate from `datatype-expansion` to `webapi-parser`. -## datatype-expansion and webapi-parser -While `datatype-expansion` is a utility tool to expand a given type and create a canonical form, `webapi-parser` is an API Spec parser which currently supports RAML 0.8, RAML 1.0, OAS 2.0 and OAS 3.0(beta). +## datatype-expansion vs. webapi-parser +While `datatype-expansion` is a utility tool that expands a given type and creates a canonical form, `webapi-parser` is an API definition parser which currently supports RAML 0.8, RAML 1.0, OAS 2.0 and OAS 3.0(beta). -Among other `webapi-parser` functionality is an API/process called "resolution". This process is performed by syntax-specific `.resolve()` methods of all supported API syntaxes (RAML, OAS, AMF Graph). +Among the several steps of `webapi-parser`'s parsing process, there is a step called "resolution". This step is performed by the `.resolve()` method and this method is available in all supported API specification formats (RAML, OAS, AMF Graph). -Resolving produces a "flat" document/model with all the references replaced by redundant copies of an actual data, thus replacing functionality offered by `datatype-expansion`. `webapi-parser` can resolve RAML APIs and all the supported fragments (Library, DataType, etc.). +Resolving produces a "flat" model with all references replaced by redundant copies of actual referenced data. `webapi-parser` can resolve RAML API definitions and all of RAML's typed fragments (Library, DataType, etc.). -For more details or resolution process, please see the [Resolving a "WebApi" Model](https://raml-org.github.io/webapi-parser/resolving.html) document. +For more details on the resolution process, you can read the [Resolving a "WebApi" Model](https://raml-org.github.io/webapi-parser/resolving.html) guide. ## Installing webapi-parser -To install `webapi-parser` follow guidelines from the respective [readme section](https://github.com/raml-org/webapi-parser#javascript). +To install `webapi-parser`, follow the steps described in the [README](https://github.com/raml-org/webapi-parser#javascript). ## Example project ### Files @@ -91,9 +91,9 @@ types: ``` ### Explanation -Now considering the input (`input.raml`) let's describe contents of `index.js` line-by-line. +Considering the input (`input.raml`), let's review `index.js` line-by-line. -First all the necessary modules are imported. This includes `webapi-parser` namespace `WebApiParser` which contains most of the lib's public API: +All the necessary modules are imported. This includes `webapi-parser` namespace `WebApiParser` which contains most of the lib's public API: ```js const wap = require('webapi-parser').WebApiParser const path = require('path') @@ -110,7 +110,7 @@ Next line is where the magic happens. By calling the `.resolve()` method parsed const resolved = await wap.raml10.resolve(model) ``` -To conclude our processing we generate output RAML file (`output.raml`) from the resolved model: +To conclude, we generate the output RAML file (`output.raml`) from the resolved model: ```js const outPath = path.join(__dirname, './output.raml') await wap.raml10.generateFile(resolved, `file://${outPath}`) @@ -121,9 +121,9 @@ We could also generate a RAML string instead of the file by calling: const ramlString = wap.raml10.generateString(resolved) ``` -Feel free to inspect contents of the `output.raml` file above and note how types definitions and their inheritance was flattened/expanded. +Feel free to inspect contents of the `output.raml` file above and note how type definitions and their respective inheritances were flattened/expanded. -Note that "WebApi" Model functionality isn't limited to output generation. It can also be inspected and altered in JS and Java code and converter to other API spec formats (OAS2.0, OAS 3.0, etc.). +Note that the "WebApi Model" functionality isn't limited to output generation. It can also be inspected and altered in JavaScript or Java code, and converter to other API specification formats (OAS2.0, OAS 3.0, etc). ## Need Assistance? Here are the things to do if you have more questions: @@ -131,3 +131,4 @@ Here are the things to do if you have more questions: * 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) +* Join the [RAML Community Slack workspace](https://raml.org/slack)