Update: Complete new documentation for the element. Work in progress.…

… Missing rest of the documentation for styling.

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Guide for Contributors
+
+The API Console is open and we encourage the community to contribute in the project. However, it is very important to follow couple of simple rules when you create an issue report or send a pull request.
+
+## Reporting an issue
+
+**If this is feature request**, please provide a clear description of the feature. I've created a [document][87714bdc] that may help you fill up a feature request. But basically you should answer this questions:
+
+- Who will benefit from this feature? _("Someone who is trying to...")_
+- What's the use cases (when the feature will be used)? _("When API specification contains...")_
+- What the user gain by having this feature? _("I should be able to see...")_
+
+An overview of the feature would be nice as well.
+
+**When you're filling a bug report**, please be as much specific as you can, and add a clear description of the bug, console logs if available and your expectations. You're welcome to use following template:
+
+```markdown
+HTTP method documentation is missing property in the properties documentation table. The property is defined inline after the body inherits from a type.
+
+## Expected outcome
+
+There should be a documentation for all inherited properties from the type and property defined inline in body declaration.
+
+## Actual outcome
+
+Only inherited from the type properties are displayed in the documentation table.
+
+## Steps to reproduce
+
+1. Load this test API https://domain.com/api.raml
+2. Go to Resource > POST
+3. Go to request body > properties documentation.
+
+## Was this working before?
+
+- [ ] Yes, it was working before
+- [ ] No, it was already broken
+- [x] I don't know / not sure
+
+## Affected browsers
+
+- [x] All or I don't know
+- [ ] Chrome
+- [ ] Firefox
+- [ ] Internet Explorer <\3
+- [ ] Edge
+- [ ] Safari
+- [ ] Other (please, specify)
+```
+
+## Submitting Pull Requests
+
+API Console uses ARC (Advanced REST Client) elements so **while developing**, be sure that you follow the [design guidelines] for ARC.
+
+**Before creating a pull request**, fill up `changelog.md` file with changes made by you. It is the best way of keeping track of change reasons. Try be very specific and put there only essential information about the changes.
+
+Then a good idea is to test your code. Use [Web Component Tester], a great tool created by the Polymer team, to test your code. Each element contains it's own test. Check how it works and design the test case for your changes.
+
+Please ensure that an issue exists for the corresponding change in the pull request that you intend to make. **If an issue does not exist, please create one per the guidelines above**. The goal is to discuss the design and necessity of the proposed change with API Console / ARC authors and community before diving into a pull request.
+
+When submitting pull requests, please provide:
+
+1. **A reference to the corresponding issue** or issues that will be closed by the pull request. Please refer to these issues using the following syntax:
+
+ ```markdown
+ (For a single issue)
+ Fixes #20
+
+ (For multiple issues)
+ Fixes #32, #40
+ ```
+
+ Github automatically close the issues after merging it to the master. So please, keep the format.
+
+ 2. **A succinct description of the design** used to fix any related issues. For example:
+
+ ```markdown
+ This fixes #20 by removing styles that leaked which would cause the page to turn pink whenever `some-element` is clicked.
+ ```
+
+ 3. **At least one test for each bug fixed or feature added** as part of the pull request. Pull requests that fix bugs or add features without accompanying tests will not be considered.
+
+If a proposed change contains multiple commits, please [squash commits](http://blog.steveklabnik.com/posts/2012-11-08-how-to-squash-commits-in-a-github-pull-request) to as few as is necessary to succinctly express the change.
+
+
+  [87714bdc]: https://docs.google.com/document/d/10OPWl9Hagk6Oz--VUztQBTOpm3QP2Vv__PrH3zZ7wFQ/edit?usp=sharing "Feature request file"
+  [Design guidelines]: https://github.com/jarrodek/ChromeRestClient/wiki/design
+  [Web Component Tester]: https://github.com/Polymer/web-component-tester

docs/README.md

@@ -0,0 +1,9 @@
+# API Console documentation
+
+Select a topic
+- [API Console element documentation](api-console-element.md)
+- [API Console build tools](build-tools.md)
+- [API Console configuration options](configuring-api-console.md)
+- [Handling CORS](cors.md)
+- [Passing RAML to the API Console](passing-raml-data.md)
+- [Styling the API Console](theming.md)

docs/api-console-element.md

@@ -0,0 +1,111 @@
+# Using the API Console HTML element
+
+1) Install the console as a dependency of your project. We use [bower] for this. Bower will also install dependencies of the console.
+
+```
+bower install --save mulesoft/api-console#release/4.0.0
+```
+
+2) Import the console to your page. For the element to be recognized by the browser as a new HTML element you have to include it in the page source.
+
+```html
+<link rel="import" href="bower_components/api-console/api-console.html">
+```
+
+3) Use the HTML tag
+
+```html
+<body>
+  <api-console raml="{...}"></api-console>
+</body>
+```
+
+Learn how to pass RAML data to the element in the [Passing the RAML data](passing-raml-data.md) section.
+
+Full list of available configuration options for the `api-console` element can be found in [configuring the API Console](configuring-api-console.md) document.
+
+## Setup polyfills
+
+Web components are based on four new specifications (Custom elements, shadow DOM, HTML imports and HTML template) that are not fully supported in old browsers (like IE). Also, browser vendors still discussing the HTML imports specification so it's [not yet implemented](http://caniuse.com/#feat=imports) in Edge and Firefox.
+
+If you planning to target these browsers you should include a polyfill for Web Components. The polyfill library is already included into your project (giving that you have installed the element using `bower`). It's the `bower_components/webcomponentsjs/webcomponents-lite.min.js` file.
+
+## Full web app example
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, minimum-scale=1, initial-scale=1, user-scalable=yes">
+    <title>My API documentation</title>
+    <script>
+      // Load webcomponentsjs polyfill if browser does not support native Web Components
+      (function() {
+        'use strict';
+        var onload = function() {
+          // For native Imports, manually fire WebComponentsReady so user code
+          // can use the same code path for native and polyfill'd imports.
+          if (!window.HTMLImports) {
+            document.dispatchEvent(
+              new CustomEvent('WebComponentsReady', {bubbles: true})
+            );
+          }
+        };
+
+        var webComponentsSupported = (
+          'registerElement' in document &&
+          'import' in document.createElement('link') &&
+          'content' in document.createElement('template')
+        );
+
+        if (!webComponentsSupported) {
+          var script = document.createElement('script');
+          script.async = true;
+          script.src = '/bower_components/webcomponentsjs/webcomponents-lite.min.js';
+          script.onload = onload;
+          document.head.appendChild(script);
+        } else {
+          onload();
+        }
+      })();
+    </script>
+    <link rel="import" href="/bower_components/api-console/api-console.html">
+  </head>
+<body>
+  <api-console></api-console>
+  <script>
+  function fetchApiData() {
+    // api.json contains cached results of parsing the RAML spec.
+    return fetch('./api.json')
+    .then(function(response) {
+      if (response.ok) {
+        return response.json();
+      }
+    });
+  }
+
+  function notifyInitError(message) {
+    alert('No API for you this time. ' + message);
+  }
+
+  function init() {
+    fetchApiData()
+    .then(function(json) {
+      if (json) {
+        var apiConsole = document.querySelector('api-console');
+        apiConsole.json = json;
+      } else {
+        notifyInitError('Data not available.');
+      }
+    })
+    .catch(function(cause) {
+      notifyInitError(cause.message);
+    })
+  };
+  init();
+  </script>
+</body>
+</html>
+```
+[bower]: https://bower.io/

docs/build-tools.md

@@ -0,0 +1,118 @@
+# API Console build tools
+
+The API console comes with a set of tools that will help you with creating a documentation for your API very quickly.
+
+## api-console CLI
+
+### Installation
+
+Preferred way is to install the CLI tool globally. If you can't then install it without `-g` and run the commands prefixing the `api-console` with `./node_modules/.bin/`.
+
+```shell
+$ sudo npm install -g api-console-cli
+```
+
+### Features
+
+- build - Build the api console application optimized for production
+- generate-json - Regenerates the JSON file that can be used as a data source in the Console
+
+See https://github.com/mulesoft-labs/api-console-cli for full documentation.
+
+### Examples
+
+Build the API console from the latest released version and using `https://domain.com/api.raml` as a data source.
+
+```shell
+$ api-console build https://domain.com/api.raml
+```
+
+Build the API Console from local sources (`--source api-console-release.zip`) that is a zip file of a release (`--source-is-zip`). Note that this command will automatically assume the `--json` option to be set.
+
+```shell
+$ api-console build --source api-console-release.zip --source-is-zip api.raml
+```
+
+Build the API console and generate the `api.json` file that will be included in the build.
+
+```shell
+$ api-console build --json api.raml
+```
+
+**Note** Because of series of optimizations (among others the most computing power and time consuming JavaScript compilation) it will take few minutes to build the console. You can pass `--no-optimization` flag to make the build process faster but it should be used in development environment only.
+
+## API Console node modules
+
+### api-console-builder
+
+The node module to build the API console from the api-console element either as a embeddable element or as a standalone application.
+
+See detailed documentation in the [api-console-builder](https://www.npmjs.com/package/api-console-builder) page.
+
+### Installation
+
+```shell
+$ npm i api-console-builder
+```
+
+### Examples
+
+Will build a standalone application of the API Console that uses a specific release version from GitHub as the element source and API definition from the `api.raml` file. It will generate a separate `api.json` file with RAML parsing results for faster initialization.
+
+```javascript
+const builder = require('api-console-builder');
+
+builder({
+  src: 'https://github.com/mulesoft/api-console/archive/release/4.0.0.zip',
+  dest: 'build',
+  raml: 'api.raml',
+  useJson: true,
+  verbose: true
+})
+.then(() => console.log('Build complete'))
+.catch((cause) => console.log('Build error', cause.message));
+```
+
+### raml-json-enhance-node
+
+A RAML's JSON enhancer node package to enhance JSON output of the RAML parser. Enhanced JSON to be used as an input for ARC elements and the API Console.
+
+It's ideal to use it in your CI process to replace the `api.json` file instead of regenerating the whole API console application.
+
+See detailed documentation in the [raml-json-enhance-node](https://www.npmjs.com/package/raml-json-enhance-node) page.
+
+### Installation
+
+```shell
+$ npm i raml-json-enhance-node
+```
+
+### Examples
+
+Generating enhanced JSON from the RAML file:
+
+```javascript
+const {RamlJsonGenerator} = require('raml-json-enhance-node');
+
+const enhancer = new RamlJsonGenerator('./api.raml');
+enhancer.generate()
+.then((json) => {
+  console.log(json);
+});
+```
+
+Like above but output will be saved to a file:
+
+```javascript
+const {RamlJsonGenerator} = require('raml-json-enhance-node');
+
+const enhancer = new RamlJsonGenerator('./api.raml', {
+  output: './api.json'
+});
+enhancer.generate()
+.then((json) => {
+  // The file is saved now.
+  // And the JS object is available to use.
+  console.log(json);
+});
+```