amf-client-js 5.2.0-SNAPSHOT.9 → 5.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +55 -134
  2. package/amf.js +11203 -11178
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,174 +1,95 @@
1
- [![Build Status](https://jenkins.build.msap.io/buildStatus/icon?job=application/AMF/amf/master)](https://jenkins.build.msap.io/job/application/job/AMF/job/amf/job/master/)
1
+ [![GitHub license](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/aml-org/amf/blob/master/LICENSE) [![Build Status](https://jenkins.build.msap.io/buildStatus/icon?job=application/AMF/amf/master)](https://jenkins.build.msap.io/job/application/job/AMF/job/amf/job/master/) [![Version](https://img.shields.io/github/v/release/aml-org/amf)](https://github.com/aml-org/amf/releases)
2
2
 
3
3
  # AML Modeling Framework
4
+ AMF (AML Modeling Framework) is an open-source programming framework, capable of parsing, generating and validating metadata documents defined using [AML](https://a.ml/aml-spec). It can be used as a library in Scala, Java, or JavaScript projects. The modular design of AMF facilitates creating plugins capable of parsing other metadata syntaxes not defined by AML.
4
5
 
5
- This project aims to provide a common programming interface that lets developers interact with any API specification, whether it is written in OpenAPI Specification (OAS) or RAML, similar to the way the HTML DOM allows programmatic interaction with an HTML document.
6
6
 
7
- ## Vision
7
+ # 📃 Documentation
8
+ - [The AML Project](https://a.ml)
9
+ - [AMF Documentation website](https://a.ml/docs)
10
+ - [AMF model documentation](./documentation/model.md)
11
+ - [GitHub repository of AMF code examples](https://github.com/aml-org/examples)
8
12
 
9
- The API Modeling Framework (AMF) allows users to formally describe different kinds of APIs, parse and generate instances of those APIS as sets of modular documents and store those connected descriptions into a single unified data graph.
13
+ # 📦 Artifacts
14
+ [![NPMJS](https://img.shields.io/npm/v/amf-client-js.svg)](https://www.npmjs.com/package/amf-client-js)
15
+ [![github releases](https://img.shields.io/github/v/release/aml-org/amf?label=nexus)](https://repository-master.mulesoft.org/nexus/content/repositories/releases/com/github/amlorg/amf-api-contract_2.12)
10
16
 
11
- ## Goals
12
-
13
- - Support for multiple languages with a unified output API/model for clients
14
- - Support for both, document (RAML modularity) and domain (service clients), layers
15
- - Bi-directional transformation
16
- - Support for validation at document and service layers
17
- - Produce a formal specification for the language
18
- - Extensible, single document model for multiple domain vocabularies
19
- - Consistent parsing behavior
20
-
21
- ## General scope
22
- The library supports many of the required uses cases:
23
- - Parse a 0.8 / 1.0 RAML, 2.0 / 3.0 OAS and JSON-LD AMF model.
24
- - AMF API design model creation.
25
- - Model edition.
26
- - Export to any of the mentioned standards.
27
-
28
- ## Usage
29
-
30
- To use AMF you should first generate or get the right distribution for your project and import them as dependencies.
31
-
32
- ## Installation
33
-
34
- ### Requirements
35
- * Scala 2.12.2
36
- * sbt 0.13.15
37
- * Node
38
-
39
- ### Useful sbt commands
40
-
41
- #### Test
42
- * Tests on jvm and js
43
-
44
- ```sh
45
- sbt test
46
- ```
47
-
48
- #### Coverage reports
49
- ```sh
50
- sbt coverage test coverageReport
51
- ```
52
- ### Generate artifacts directly from cloned repository
53
-
54
- ```sh
55
- sbt package
56
- ```
57
- This will generate *jvm* JARs in each of the module's targets.
58
-
59
- ```sh
60
- sbt buildJS
61
- ```
62
- This will generate a *js* artifact in ./file://amf-client/js/amf.js
63
-
64
- ### JVM artifacts
65
-
66
- To use, specify dependency.
67
-
68
- Gradle example:
69
-
70
- ```groovy
71
- dependencies {
72
- compile 'com.github.amlorg:amf-client_2.12:x.y.z'
73
- }
74
- ```
75
17
 
18
+ ## Gradle
76
19
  ```groovy
20
+ // add mulesoft repository
77
21
  repositories {
78
- ...
79
22
  maven {
80
- url 'https://repository-master.mulesoft.org/nexus/content/repositories/releases'
81
- }
82
- ...
23
+ url 'https://repository-master.mulesoft.org/nexus/content/repositories/releases'
24
+ }
25
+ }
26
+ dependencies {
27
+ compile 'com.github.amlorg:amf-api-contract_2.12:x.y.z'
83
28
  }
84
29
  ```
85
30
 
86
- Maven example:
87
-
31
+ ## Maven
88
32
  ```xml
89
33
  <dependency>
90
34
  <groupId>com.github.amlorg</groupId>
91
- <artifactId>amf-client_2.12</artifactId>
35
+ <artifactId>amf-api-contract_2.12</artifactId>
92
36
  <version>x.y.z</version>
93
37
  </dependency>
94
38
  ```
95
39
 
96
- NOTE: you may use the `-SNAPSHOT` versions of the JVM artifacts at your own risk since those snapshot versions may contain breaking changes.
97
-
98
- ### JS artifacts
40
+ NOTE: you may use the `-SNAPSHOT` versions of the artifacts at your own risk since those snapshot versions may contain breaking changes.
99
41
 
100
- Execute the command
101
-
102
- ```bash
103
- npm install --save amf-client-js
104
- ```
105
-
106
- Using *Node.js* just import it using:
42
+ ## JavaScript
107
43
  ```bash
108
- import amf from 'amf-client-js'
44
+ $ npm install --save amf-client-js
109
45
  ```
110
46
 
111
- The *amf* package will contain all exported classes:
112
- ```javascript
113
- amf.plugins.document.WebApi.register();
114
- amf.plugins.document.Vocabularies.register();
115
- amf.plugins.features.AMFValidation.register();
47
+ ## Generate artifacts directly from cloned repository
116
48
 
117
- amf.Core.init().then(function () {
118
- // AMF code here
119
- })
49
+ To build into a JVM jar:
50
+ ```sh
51
+ sbt package
120
52
  ```
121
-
122
- ### Command line usage
123
-
124
- You can build a standalone Java executable (JAR) running the following SBT target:
125
- ```bash
126
- sbt buildCommandLine
53
+ To build into a JS bundle:
54
+ ```sh
55
+ sh js-build.sh
127
56
  ```
128
57
 
129
- This will generate an executable JAR at the top level directory that can be used to execute AMF from the command line.
130
-
131
- Using this JAR, you can run tasks from command line, for instance:
132
- ```bash
133
- java -jar amf-x.y.z.jar parse -in "RAML 1.0" -mime-in "application/yaml" yourAPIfile
134
- ```
135
- or
136
- ```bash
137
- java -jar amf-x.y.z.jar validate -in "RAML 1.0" -mime-in "application/yaml" -p "RAML" yourAPIfile
138
- ```
139
- or
140
- ```bash
141
- java -jar amf-x.y.z.jar translate yourAPIOASfile --format-in "OAS 3.0" -mime-in "application/json" --format-out "RAML 1.0" -mime-out "application/raml+yaml"
142
- ```
143
- To get all available options:
144
- ```bash
145
- java -jar amf-x.y.z.jar
146
- ```
58
+ More info on how to add AMF to your project [here](https://a.ml/docs/amf/using-amf/amf_setup).
147
59
 
148
- Using this JAR you can execute AMF by passing one of the following commands:
149
60
 
150
- - parse <input_file> -in FORMAT
151
- - translate <input_file> <output_file> -in FORMAT_IN -out FORMAT_OUT
152
- - validate <input_file> -in FORMAT_IN -p VALIDATION_PROFILE
61
+ # AMF Native support
153
62
 
154
- An interactive section can be started using the `repl` command.
63
+ AMF natively supports the following formats:
64
+ - YAML
65
+ - JSON
155
66
 
156
- If you want to parse any RAML dialect other than RAML 1.0, you can pass a list of dialects to be loaded in the parser through the `dialects` option.
67
+ the following semantic models:
68
+ - WebApi (or "Web APIs" as in "APIs accessible over the network")
69
+ - AsyncApi
157
70
 
158
- Refer to the usage of the application for additional commands and explanations.
71
+ and the following syntactic models:
72
+ - JSON-LD "AMF model"
73
+ - RAML 0.8 / 1.0 (mapped to "WebApi")
74
+ - OpenAPI (OAS) 2.0 / 3.0 (mapped to "WebApi")
75
+ - AsyncAPI 2.0 (mapped to "AsyncApi")
159
76
 
160
- ## Examples
77
+ The models above and any other models may be extended and supported via custom [AML-defined models](https://a.ml/aml-spec). Other formats and models that cannot be expressed with AML may also be supported via plugins.
161
78
 
162
- Go to [amf examples repository](https://github.com/mulesoft/amf-examples) There are examples for each one of the three usages and a *converter* project that add some UI on top of the library.
79
+ ## Guaranteed output
163
80
 
164
- ## Validation
81
+ The **only** guaranteed output of AMF is the JSON-LD "AMF model". Any other output such as any output provided natively by the models listed under the section above may change at any time. This means that while the semantic representation of those outputs may remain unchanged, the syntactical expression such as the order in which the outputted metadata is expressed and any other syntax-related constructs may change from one version of AMF to another. If this is an issue for your use-case, you may consider using a custom resolution/generation pipeline.
165
82
 
166
- Validation is one of the key features of AMF. Please check the following link to get more information:
83
+ # AMF ecosystem modules
84
+ The following image shows each module in the AMF ecosystem as a dependency graph.
167
85
 
168
- [Validation insights](./documentation/validation.md)
86
+ For AMF adopters it is recommended to use the `amf-api-contract` module which contains transitive dependencies with every
87
+ module in the ecosystem except the CLI. For AML adopters (with no Web API nor Custom validation features usage) it is recommended to
88
+ adopt the `amf-aml` module which includes parsing, validation & resolution for AML documents only. For more details on
89
+ AML visit the [AML repository]("https://github.com/aml-org/amf-aml").
169
90
 
170
- ## Want to learn more?
171
- [Click here for more documentation and playground](https://a.ml)
91
+ ![AMF ecosystem modules](./amf-ecosystem-modules.png)
92
+ The `amf-api-contract` and `amf-aml` are the recommended modules for AMF and AML adopters respectively.
172
93
 
173
- ## Want to contribute?
174
- If you are interested in contributing code to this project, thanks! Please [read and accept the Contributors Agreement](https://api-notebook.anypoint.mulesoft.com/notebooks#380297ed0e474010ff43). This should automatically create a Github issue with the record of your signature [here](https://github.com/mulesoft/contributor-agreements/issues). If for any reason, you do not see your signature there, please contact us.
94
+ ## Contributing
95
+ If you are interested in contributing to this project, please make sure to read our [contributing guidelines](./CONTRIBUTING.md).