You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+22-2Lines changed: 22 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,11 @@
1
+
**See live example of the API console in our [demo application].**
2
+
1
3
# The API Console
2
4
3
5
MuleSoft's API Console is a full-fledged API documentation tool that generates mobile-friendly web documentation based on RAML (Restful API Modeling Language) documents. In addition to providing documentation, the tool provides the capability for users to try out requests on the fly.
Copy file name to clipboardExpand all lines: docs/configuring-api-console.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,7 +41,9 @@ The following table describes HTML attributes.
41
41
|`manual-navigation`| Disables navigation in the drawer and renders the navigation full screen when requested. Use in the narrow layouts with the `narrow` property. Set the `navigationOpened` property to `true` or `false` to open/close the navigation. |`Boolean`|
42
42
|`navigation-opened`| If set, the `manual-navigation` attribute is set, and the full screen navigation will open/close. |`Boolean`|
43
43
|`bower-location`| If the path to the `bower_components` is different than default (in the root path) then set this attribute to point the location of the folder, including folder name. |`String`|
44
-
| `no-url-editor` | If set, the URL editor is hidden in the Try it panel. The editor is still attached to the DOM but it's invisible to the user. | `Boolean`
44
+
|`no-url-editor`| If set, the URL editor is hidden in the Try it panel. The editor is still attached to the DOM but it's invisible to the user. |`Boolean`|
45
+
| `base-uri` | Used to replace RAML's base URI. Once set it updates the request URL in the request panel (try it). The URL will always contain the same base URL until the attribute is cleared (removed, set to `null`, `undefined` or `false`) | `String`
The default version of the **API console does not contain the RAML parser**. It is by design to minimize the size of the console and to optimize startup time.
4
4
5
-
Web components are asynchronous by nature. Importing the elements,
6
-
registering them in the DOM, and finally initializing an element is done asynchronously. Therefore, you can't expect the element to work immediately after loading the page as a typical HTML element does. Consider the following example:
5
+
You can use the console with the RAML parser by setting up the build / CLI tools or by adding the dependency manually. **This document describes why the parser has been removed from the core console code and how to use the parser with new console.**
var parser =document.querySelector('raml-js-parser');
13
-
parser.loadApi(apiFileUrl);
14
-
</script>
15
-
```
7
+
## Performance of the API console
16
8
17
-
Running this code as the page loads throws a `TypeError` with the message: `parser.loadApi is not a function`.
9
+
One of the challenges standing before us when we started developing version 4 of the API console was the performance. This is wide area so here we'll limit it to size of the source code and initial start time.
18
10
19
-
At the time of execution of this script block, the browser knows nothing about the `raml-js-parser` element. At this time, the element is an instance of `HTMLUnknownElement`.
11
+
Before we go into detailed performance issues description read why we use the enhancer alongside the JS parser.
20
12
21
-
The browser has to import the source of the element first, and then the Polymer library has to register custom HTML element called `raml-js-parser`.
22
13
23
-
To run the code properly you have to listen for the `WebComponentsReady` event. It's fired when the elements are ready to use.
14
+
### RAML <> JavaScript enhancer
15
+
16
+
As you may already know the API console consists of over 150 web components. They are responsible for displaying the documentation, rendering the request and response panels in the "try it" function and to make test requests to an endpoint.
17
+
18
+
[RAML's JavaScript parser][5] has been created to give access to RAML document's [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree). It is very inconvenient to use it with HTML templating systems (like Polymer's or Angular's). The parser simply hasn't been created for this use case. Apart from offering the AST the parser produces a JavaScript object. The object can be used in many cases in JavaScript environment. However the output is not as helpful in the world of web components.
19
+
20
+
The components serves one purpose and are responsible for a single task in the API console. For example there is an element that renders annotation added to a type only. Because of that not every element need to have access to full RAML description. It only uses part of the documentation that it is going to use. Parser's JavaScript output gives literally translated YAML structure to a JavaScript object. It means that if you, for example, declare a type on a `body` declaration as a name of previously defined type on the root of the RAML document, the parser's output is this name and not the type definition. Therefore parser JavaScript output requires additional transformations before it can be used with web components architecture.
21
+
22
+
For the API Console we use our fork of the [raml2obj][11] library as a base transformer. With the [expansion library][12] we've created an web component [raml-json-enhance][3] and node module [raml-json-enhance-node][4] that transforms parser's output to a form that can be used with the components of the API console.
23
+
24
+
Output of the enhancer is then to be used as an input data of the API console. Use of the enhancer also allowed us to minimize code base of all the web components because they don't need to contain code to compute missing properties.
25
+
26
+
### Console source size
27
+
28
+
The first issue is the size of the console. When you install dependencies of the console it turns out that the whole project is about 40MB (excluding `node_modules`). That's a lot but this is a development version of the console.
29
+
We have prepared a [build tools][1] for the console, that works on top of Polymer's [build tools][1] to produce production ready version of the console. With optimization option enabled (default behavior) it produces a single file with all web components definitions concatenated to a single 2MB file. It is still quite a lot but so far we were able to reduce the code to this size.
30
+
31
+
### Console startup time
32
+
33
+
Big issue for the API console in version < 4.0.0 was startup time. Each time the console was loaded into the browser it had to download all RAML sources, parse it and then render the console based on JavaScript parser output. In many cases two first steps are simply redundant. If the API specification doesn't change very often there's no reason to parse the RAML each time the console is opened. We've replaced this part with prebuilt of the parser's output file that contains transformed RMAL data. In case of huge and complicated APIs it can significantly reduce startup time.
34
+
35
+
Separation of the data source and the API console has additional advantage. In new architecture, when source RAML changes you can just rebuild the JSON file with new data instead of rebuilding the console. This speeds up publish time of new API an can be easily automated in your [CI pipeline][10].
36
+
37
+
Our [build tools][1] gives you options to include the parser and enhancer to the final build so, depending on your use case, you can optimize startup time of the console.
38
+
39
+
## Installing parser and enhancer
40
+
41
+
You can install parser and enhancer in your project by calling [bower][9] command:
You can use `package.json` script declaration for the same command:
38
48
39
-
The API console web component requires a JavaScript object produced by the [raml-js-parser] and [raml-js-enhance] elements. Parsing and enhancing RAML is not part of the `api-console` element and must be performed separately as described below.
**Head's up!** You can use our [build tools] to generate the JSON file from the RAML in Node (using node modules) and Shell (with the API Console CLI tool).
58
+
Or in combination with installation of the console:
42
59
43
-
Use the [raml-js-parser] element to parse YAML data or to download RAML from a remote location. __Note__: You may also use our [raml-js-parser-2] node library as it yields the same output.
Then, you **must** use the [raml-js-enhance] element to produce data output that is recognizable by the `api-console`. The enhancer creates a common data structure and expands RAML types by flattening any type having a complex inheritance structure.
64
+
It installs source files in `bower_components` directory. You can then reference those files in the `import` directive. After the components are imported and registered you can use them as described in our [web components guide][2].
46
65
47
-
Elements used to build API Console expect the JSON object to contain complete data about a method / endpoint / type / security scheme and so on. They do not look into nor have access to the data in the root of RAML definition. The enhancer replaces objects with arrays, adding a `key` property to each item, for use in a templating system. Also, the `example` property of the RAML is always translated to an `examples` array. Finally, the enhancer creates a `fullUrl` property on each HTTP method so the console doesn't need to compute it each time you open the documentation page.
66
+
Also check out our usage guide of the `<api-console>` element in our [element's guide][8].
1) After the elements are initialized, the`WebComponentsReady` event occurs and calls the `loadApi()` function on the [raml-js-parser] element.
72
-
2) The element fires the `api-parse-ready` custom event that should be handled by the application and the result of parsing (`e.detail.json.specification`) should be passed to the enhancer's `json` property.
73
-
3) When the enhancer transforms the object, it fires the `raml-json-enhance-ready` custom event. The result is in the `e.detail.json` property.
103
+
The `json` attribute set on `raml-js-parser` element tells the parser that the output should be a JavaScript object instead of the AST.
74
104
75
-
Parsing and enhancing can consumes significant system resources, depending on the RAML structure and number of referenced files. It is a good idea to do perform these operations once and cache the results. Then, when the user visits the page again, restore the cached JSON object, and pass it as the `api-console` parameter as discussed below.
76
-
77
-
### Setting RAML data as an HTML attribute
105
+
### Setting RAML data as a HTML attribute
78
106
79
107
The basic method for determining what API Console displays is to use the `raml` attribute. The attribute accepts the JavaScript object produced by the parser and the enhancer described above.
80
108
@@ -96,19 +124,28 @@ The `<api-console>` element also has a convenient `json-file` attribute that can
96
124
<api-consolejson-file="api.json"></api-console>
97
125
```
98
126
99
-
This method is the most flexible method of passing the RAML data. You can use our [build tools] to regenerate the `api.json` file in your CI process automatically as soon as you publish changes in your API.
127
+
This method is the most flexible method of passing the RAML data. You can use our [build tools][1] to regenerate the `api.json` file in your CI process automatically as soon as you publish changes in your API.
100
128
101
129
### Using RAML aware to pass the data
102
130
103
-
API console internally uses the [raml-aware] element.
131
+
API console internally uses the [raml-aware][6] element.
104
132
This element can be used to pass the RAML data to the console if direct access to the
105
-
element is not possible, for example, if the console is encapsulated in the [shadow DOM].
133
+
element is not possible, for example, if the console is encapsulated in the [shadow DOM][7].
134
+
135
+
See the [raml-aware][6] documentation page for more information.
136
+
137
+
#### Install
106
138
107
-
See the [raml-aware] documentation page for more information.
0 commit comments