Skip to content
This repository was archived by the owner on Jan 21, 2024. It is now read-only.

Commit 5bfcaaf

Browse files
jstoikojstoiko
committed
reworked documentation a bit
1 parent cbc411e commit 5bfcaaf

10 files changed

+71
-88
lines changed

‎README.md

+12-13
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,16 @@ This project is a thin wrapper that exposes API Spec-related capabilities from [
1111
| ---- | ---------- | ---- |
1212
| **Installation** | [NPM](#javascript) | [Gradle/Maven](#java) |
1313
| **Documentation** | [JavaScript Typedoc](https://raml-org.github.io/webapi-parser/js/modules/_webapi_parser_.html) | [Javadocs](https://raml-org.github.io/webapi-parser/java/index.html) |
14-
| **Object-oriented interface** | [WebApi Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html) | [WebApi Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html) |
14+
| **Object-oriented interface** | ["WebApi" Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html) | ["WebApi" Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html) |
1515
| **Package** | [![NPMJS](https://img.shields.io/static/v1.svg?style=flat&logo=npm&label=%20&labelColor=white&color=CB3837&message=NPMJS)](https://) | [![Maven Central](https://img.shields.io/static/v1.svg?style=flat&logo=java&label=%20&labelColor=white&labelColor=007396&color=007396&message=Maven%20Central)](https://) |
1616

1717

18-
## Quickstart guides
19-
* [Resolving an API Spec](https://raml-org.github.io/webapi-parser/common/resolution)
20-
* [Navigating an API Spec](https://raml-org.github.io/webapi-parser/common/model-navigation)
21-
* [Constructing an API Spec](https://raml-org.github.io/webapi-parser/common/api-construction)
22-
* Translating/converting API Spec formats:
23-
* [RAML Data Type -> JSON Schema conversion](https://raml-org.github.io/webapi-parser/common/conversion-raml-json)
24-
* [JSON Schema -> RAML Data Type conversion](https://raml-org.github.io/webapi-parser/common/conversion-json-raml)
18+
## Examples
19+
* [Resolving a "WebApi" Model](https://raml-org.github.io/webapi-parser/resolving)
20+
* [Navigating a "WebApi" Model](https://raml-org.github.io/webapi-parser/navigating)
21+
* [Constructing a "WebApi" Model](https://raml-org.github.io/webapi-parser/constructing)
22+
* [Translating RAML DataTypes to JSON Schemas](https://raml-org.github.io/webapi-parser/translating-raml-json)
23+
* [Translating JSON Schemas to RAML DataTypes](https://raml-org.github.io/webapi-parser/translating-json-raml)
2524

2625
## Installation
2726

@@ -32,15 +31,15 @@ Install the npm package:
3231
$ npm install webapi-parser
3332
```
3433

35-
and then require/reference as follows:
34+
and require/reference as follows:
3635
```js
3736
const wap = require('webapi-parser').WebApiParser
3837
```
3938

40-
You can check the [JavaScript examples directory](https://github.com/raml-org/webapi-parser/tree/master/examples/js/) for some usage examples.
39+
See the [JavaScript examples directory](https://github.com/raml-org/webapi-parser/tree/master/examples/js/) for some usage examples.
4140

4241
### Java
43-
To use, you'll need to specify `webapi-parser` as a dependency and set both MuleSoft and Jitpack repositories.
42+
Specify `webapi-parser` as a dependency and set both MuleSoft and Jitpack repositories.
4443

4544
Gradle:
4645
```groovy
@@ -79,7 +78,7 @@ Maven:
7978
</repositories>
8079
```
8180

82-
You can check the [Java examples directory](https://github.com/raml-org/webapi-parser/tree/master/examples/java/) for some usage examples.
81+
See the [Java examples directory](https://github.com/raml-org/webapi-parser/tree/master/examples/java/) for some usage examples.
8382

8483
---
85-
If you wish to contribute to this project, see our [Contribution Guidelines](https://github.com/raml-org/webapi-parser/tree/master/CONTRIBUTING.md).
84+
If you wish to contribute to this project, please review our [Contribution Guidelines](https://github.com/raml-org/webapi-parser/tree/master/CONTRIBUTING.md).

‎docs/common/api-construction.md renamed to ‎docs/constructing.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# API construction
1+
# Constructing a "WebApi" Model
22
Using `webapi-parser` it is possible to construct an API in all supported formats by hand. These construction methods can also be used to edit a parsed document.
33

44
Below is a simplified example of constructing RAML 1.0 API.

‎docs/common/model-navigation.md renamed to ‎docs/navigating.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# WebApi Model navigation
1+
# Navigating a "WebApi" Model
22
Using `webapi-parser` it is possible to navigate parsed document and extract data like response codes, titles, descriptions, data types, etc., from it.
33

44
Below is a simplified example of navigating RAML 1.0 API.

‎docs/common/resolution.md renamed to ‎docs/resolving.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Resolution
1+
# Resolving a "WebApi" Model
22
This document describes `webapi-parser` process called "resolution". This process is performed by syntax-specific `.resolve()` methods of all supported API syntaxes (RAML, OAS, AMF Graph).
33

44
## Input and Output

‎docs/common/conversion-json-raml.md renamed to ‎docs/translating-json-raml.md

+10-14
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,10 @@
1-
# JSON Schema -> RAML Data Type conversion
2-
Using `webapi-parser` and [WebApi Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html), it is possible to convert JSON Schemas to RAML Datatypes.
1+
# Translating JSON Schemas to RAML DataTypes
2+
Using `webapi-parser` and [WebApi Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html), it is possible to translate JSON Schemas to RAML Datatypes.
33

4-
Please refer to [complete examples](#complete-examples) for more advanced use cases.
4+
You can take a look at the [complete examples](#complete-examples) for more advanced use-cases.
55

66
## Quick start
7-
8-
To convert JSON Schema to RAML Data Type, parse the document of your choice, reach data type using WebApi Model and call its `.toRamlDatatype()` method (or property in JS case). Output of the method is RAML 1.0 Library string containing converted type.
9-
10-
To convert plain JSON Schema string to RAML DataType it has to be wrapped in a OAS 2.0 document.
7+
To translate a JSON Schema to a RAML DataType, you can parse a JSON containing one or more JSON Schemas, then select the data type/schema using the [WebApi Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html) and call its `.toRamlDatatype()` method (or property in JavaScript). The output of the method is a RAML 1.0 Library string containing the translated type. Note that the JSON Schema must be wrapped in an OAS 2.0 document.
118

129
```js
1310
// js
@@ -38,8 +35,7 @@ async function main () {
3835
// Parse an API document string
3936
const model = await wap.oas20.parse(JSON.stringify(parsedSchema))
4037

41-
// Convert type from "definitions".
42-
// Type can be picked using utility functions.
38+
// Type can be selected using the utility function `getDeclarationByName()`
4339
console.log(
4440
'RAML Data Type from definitions using util:\n',
4541
model.getDeclarationByName('User').toRamlDatatype)
@@ -50,7 +46,7 @@ main()
5046

5147
```java
5248
// java
53-
package co.acme.convert;
49+
package co.acme.translate;
5450

5551
import webapi.Oas20;
5652
import webapi.WebApiDocument;
@@ -60,7 +56,7 @@ import amf.client.model.domain.*;
6056
import java.util.concurrent.ExecutionException;
6157

6258
public class JsonSchemaToRamlDt {
63-
public static void convertFromApi() throws InterruptedException, ExecutionException {
59+
public static void translateFromApi() throws InterruptedException, ExecutionException {
6460
String jsonSchema = "{\n" +
6561
"\"$schema\": \"http://json-schema.org/draft-04/schema\",\n" +
6662
"\"type\": \"object\",\n" +
@@ -76,7 +72,7 @@ public class JsonSchemaToRamlDt {
7672
jsonSchema);
7773
WebApiDocument doc = (WebApiDocument) Oas20.parse(oasDoc).get();
7874

79-
// Convert type from root. Type can be picked using utility functions
75+
// Type can be selected using the utility function `getDeclarationByName()`
8076
NodeShape user1 = (NodeShape) doc.getDeclarationByName("User");
8177
System.out.println(
8278
"RAML Data Type from definitions using util:\n" +
@@ -86,5 +82,5 @@ public class JsonSchemaToRamlDt {
8682
```
8783

8884
## Complete examples
89-
* [JavaScript example](https://github.com/raml-org/webapi-parser/blob/master/examples/js/convert-jsonschema-ramldt.js)
90-
* [Java example](https://github.com/raml-org/webapi-parser/blob/master/examples/java/src/main/java/co/acme/convert/JsonSchemaToRamlDt.java)
85+
* [JavaScript example](https://github.com/raml-org/webapi-parser/blob/master/examples/js/jsonschema-ramldt.js)
86+
* [Java example](https://github.com/raml-org/webapi-parser/blob/master/examples/java/src/main/java/co/acme/translate/JsonSchemaToRamlDt.java)

‎docs/common/conversion-raml-json.md renamed to ‎docs/translating-raml-json.md

+13-13
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
1-
# RAML Data Type -> JSON Schema conversion
2-
Using `webapi-parser` and [WebApi Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html) it is possible to convert RAML 1.0 Data Type from RAML 1.0 API, RAML 1.0 Library or RAML 1.0 DataType Fragment to corresponding JSON Schema.
1+
# Translating RAML DataTypes to JSON Schemas
2+
Using `webapi-parser` and [WebApi Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html), it is possible to translate RAML 1.0 DataTypes contained inside RAML 1.0, RAML 1.0 Library and RAML 1.0 DataType documents to JSON Schemas.
33

4-
Please refer to [complete examples](#complete-examples) for more advanced use cases.
4+
You can take a look at the [complete examples](#complete-examples) for more advanced use cases.
55

66
## Quick start
7-
8-
To convert RAML Data Type to JSON Schema, parse RAML document, reach data type using WebApi Model and call its `.toJsonSchema()` method (or property in JS case). Output of the methods is JSON Schema string of converted type.
7+
To translate a RAML DataType to a JSON Schema, you can parse a RAML document, then select the data type using [WebApi Model](https://raml-org.github.io/webapi-parser/js/classes/_webapi_parser_.webapibaseunit.html) and call its `.toJsonSchema()` method (or property in JavaScript). The output of the method is a JSON Schema string representating the original RAML DataType.
98

109
```js
1110
// js
@@ -23,9 +22,10 @@ const ramlLibrary = `
2322

2423
async function main () {
2524
const libModel = await wap.raml10.parse(ramlLibrary)
26-
// Convert type from root. Type can be picked using utility functions
25+
// Type can be selected using the utility function `getDeclarationByName()`
2726
console.log(libModel.getDeclarationByName('Book').toJsonSchema)
28-
// Type can also be picked by index.
27+
28+
// Type can also be selected by index
2929
console.log(libModel.declares[0].toJsonSchema)
3030
}
3131

@@ -34,7 +34,7 @@ main()
3434

3535
```java
3636
// java
37-
package co.acme.convert;
37+
package co.acme.translate;
3838

3939
import webapi.Raml10;
4040
import amf.client.model.document.*;
@@ -43,7 +43,7 @@ import amf.client.model.domain.*;
4343
import java.util.concurrent.ExecutionException;
4444

4545
public class RamlToJsonSchema {
46-
public static void convertFromApi() throws InterruptedException, ExecutionException {
46+
public static void translateFromApi() throws InterruptedException, ExecutionException {
4747
String inp ="#%RAML 1.0 Library\n" +
4848
"types:\n" +
4949
" Book:\n" +
@@ -52,17 +52,17 @@ public class RamlToJsonSchema {
5252
" title: string\n" +
5353
" author: string\n";
5454
Module doc = (Module) Raml10.parse(inp).get();
55-
// Convert type from root. Type can be picked using utility functions
55+
// Type can be selected using the utility function `getDeclarationByName()`
5656
NodeShape book = (NodeShape) doc.getDeclarationByName("Book").get();
5757
System.out.println(book.toJsonSchema());
5858

59-
// Type can also be picked by index.
59+
// Type can also be selected by index
6060
NodeShape book2 = (NodeShape) doc.declares().get(0);
6161
System.out.println(book2.toJsonSchema());
6262
}
6363
}
6464
```
6565

6666
## Complete examples
67-
* [JavaScript example](https://github.com/raml-org/webapi-parser/blob/master/examples/js/convert-ramldt-jsonschema.js)
68-
* [Java example](https://github.com/raml-org/webapi-parser/blob/master/examples/java/src/main/java/co/acme/convert/RamlDtToJsonSchema.java)
67+
* [JavaScript example](https://github.com/raml-org/webapi-parser/blob/master/examples/js/ramldt-jsonschema.js)
68+
* [Java example](https://github.com/raml-org/webapi-parser/blob/master/examples/java/src/main/java/co/acme/translate/RamlDtToJsonSchema.java)

‎examples/java/src/main/java/co/acme/convert/JsonSchemaToRamlDt.java renamed to ‎examples/java/src/main/java/co/acme/translate/JsonSchemaToRamlDt.java

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package co.acme.convert;
1+
package co.acme.translate;
22

33
import webapi.Oas20;
44
import webapi.WebApiDocument;
@@ -9,7 +9,7 @@
99

1010
public class JsonSchemaToRamlDt {
1111

12-
// Example of converting single JSON Schema to RAML Data Type
12+
// Example of translating a standalone JSON Schema to a RAML Data Type
1313
public static void convertFromApi() throws InterruptedException, ExecutionException {
1414
String jsonSchema = "{\n" +
1515
"\"$schema\": \"http://json-schema.org/draft-04/schema\",\n" +
@@ -26,13 +26,13 @@ public static void convertFromApi() throws InterruptedException, ExecutionExcept
2626
jsonSchema);
2727
WebApiDocument doc = (WebApiDocument) Oas20.parse(oasDoc).get();
2828

29-
// Convert type from root. Type can be picked using utility functions
29+
// Type can be accessed using the utility function `getDeclarationByName()`
3030
NodeShape user1 = (NodeShape) doc.getDeclarationByName("User");
3131
System.out.println(
3232
"RAML Data Type from definitions using util:\n" +
3333
user1.toRamlDatatype());
3434

35-
// Type can also be picked by index.
35+
// Type can also be accessed by index
3636
NodeShape user2 = (NodeShape) doc.declares().get(0);
3737
System.out.println(
3838
"RAML Data Type from definitions by index:\n" +

‎examples/java/src/main/java/co/acme/convert/RamlDtToJsonSchema.java renamed to ‎examples/java/src/main/java/co/acme/translate/RamlDtToJsonSchema.java

+13-15
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package co.acme.convert;
1+
package co.acme.translate;
22

33
import webapi.Raml10;
44
import webapi.WebApiDocument;
@@ -11,8 +11,8 @@
1111

1212
public class RamlDtToJsonSchema {
1313

14-
// Example of converting single RAML Data Type from RAML 1.0 API Document string
15-
public static void convertFromApi() throws InterruptedException, ExecutionException {
14+
// Example of translating a single RAML DataType from a RAML 1.0 API Document string
15+
public static void translateFromApi() throws InterruptedException, ExecutionException {
1616
String inp ="#%RAML 1.0\n" +
1717
"title: API with Types\n" +
1818
"types:\n" +
@@ -34,19 +34,17 @@ public static void convertFromApi() throws InterruptedException, ExecutionExcept
3434
" type: User";
3535
WebApiDocument doc = (WebApiDocument) Raml10.parse(inp).get();
3636

37-
// Convert type from root. Type can be picked using utility functions
37+
// Type can be accessed using the utility function `getDeclarationByName()`
3838
NodeShape user = (NodeShape) doc.getDeclarationByName("User");
3939
System.out.println("JSON from API root using util:\n" + user.toJsonSchema());
4040

41-
// Type can also be picked by index.
41+
// Type can also be accessed by index.
4242
NodeShape user2 = (NodeShape) doc.declares().get(0);
4343
System.out.println("JSON from API root by index:\n" + user2.toJsonSchema());
4444

45-
// To convert type referenced in response payload, model needs to be
46-
// resolved first.
47-
// Note we are picking first payload of first response of first
48-
// method etc here.
45+
// To translate types referenced in a response payload, the model needs to be resolved first
4946
WebApiDocument resolved = (WebApiDocument) Raml10.resolve(doc).get();
47+
// Note that the .get(0) below correspond to the 1st payload of the 1st response of the 1st method, etc..
5048
WebApi api = (WebApi) resolved.encodes();
5149
EndPoint users = (EndPoint) api.endPoints().get(0);
5250
Operation getUsers = (Operation) users.operations().get(0);
@@ -55,8 +53,8 @@ public static void convertFromApi() throws InterruptedException, ExecutionExcept
5553
System.out.println("JSON from resolved API:\n" + user3.toJsonSchema());
5654
}
5755

58-
// Example of converting single RAML Data Type from RAML 1.0 Library string
59-
public static void convertFromLibrary() throws InterruptedException, ExecutionException {
56+
// Example of translating a RAML DataType contained im a RAML 1.0 Library string
57+
public static void translateFromLibrary() throws InterruptedException, ExecutionException {
6058
String inp ="#%RAML 1.0 Library\n" +
6159
"types:\n" +
6260
" Book:\n" +
@@ -65,17 +63,17 @@ public static void convertFromLibrary() throws InterruptedException, ExecutionEx
6563
" title: string\n" +
6664
" author: string\n";
6765
WebApiModule doc = (WebApiModule) Raml10.parse(inp).get();
68-
// Convert type from root. Type can be picked using utility functions
66+
// Type can be accessed using utility function `getDeclarationByName()`
6967
NodeShape book = (NodeShape) doc.getDeclarationByName("Book");
7068
System.out.println("JSON from Library root using util:\n" + book.toJsonSchema());
7169

72-
// Type can also be picked by index.
70+
// Type can also be accessed by index
7371
NodeShape book2 = (NodeShape) doc.declares().get(0);
7472
System.out.println("JSON from Library root by index:\n" + book2.toJsonSchema());
7573
}
7674

77-
// Example of converting single RAML Data Type from RAML 1.0 DataType Fragment string
78-
public static void convertFromDataType() throws InterruptedException, ExecutionException {
75+
// Example of translating a RAML DataType contained in a RAML 1.0 DataType string
76+
public static void translateFromDataType() throws InterruptedException, ExecutionException {
7977
String inp ="#%RAML 1.0 DataType\n" +
8078
"type: object\n" +
8179
"properties:\n" +

‎examples/js/convert-jsonschema-ramldt.js renamed to ‎examples/js/jsonschema-ramldt.js

+6-7
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* Example of converting JSON Schema to RAML Data Type using WebApi Model.
2+
* Example of translating a JSON Schema to a RAML DataType using WebApi Model
33
*/
44
const wap = require('webapi-parser').WebApiParser
55
const path = require('path')
@@ -25,16 +25,15 @@ async function main () {
2525
}
2626
}
2727

28-
// Parse an API document string
28+
// Parsing an OAS 2.0 string
2929
const model = await wap.oas20.parse(JSON.stringify(parsedSchema))
30-
31-
// Convert type from "definitions".
32-
// Type can be picked using utility functions.
30+
31+
// Type can be accessed using utility function `model.getDeclarationByName()`
3332
console.log(
3433
'RAML Data Type from definitions using util:\n',
3534
model.getDeclarationByName('User').toRamlDatatype)
36-
37-
// Type can also be picked by index.
35+
36+
// Type can also be accessed by index
3837
console.log(
3938
'RAML Data Type from definitions by index:\n',
4039
model.declares[0].toRamlDatatype)

0 commit comments

Comments
 (0)