Skip to content

Commit

Permalink
docs: updatoing readme file for the preview version
Browse files Browse the repository at this point in the history
  • Loading branch information
@jarrodek
jarrodek committed Aug 30, 2019
1 parent 70f21ca commit 3112cf3
Showing 1 changed file with 58 additions and 166 deletions.
224 changes: 58 additions & 166 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,146 +1,11 @@
__See live example of the API console in our [demo application][].__

# The API Console

MuleSoft's API Console is a full-fledged API documentation tool that generates mobile-friendly web documentation based on RAML (Restful API Modeling Language) or OAS (Open API specification) documents. In addition to providing documentation, the tool provides the capability for users to try out requests on the fly.

![API console design](docs/APIC-main-promo.png)

## API console 6.0 is here!

Version 6 comes with ES6 module imports support! No more Bower and HTML imports :) See changelog for full list of changes.

### AMF (AML Modeling Framework) support

We are working very hard to deliver first in class solutions for API documentation.
MuleSoft's AMF allows to parse any* API document and produces common data model. API console consumes this model instead of RAML JS parser's.

\* Currently AMF supports RAML 0.8, RAML 1.0, OAS 2.0 and OAS 3.0 (in beta). It can be extended by defining new vocabulary to support other API spec formats.

### Re-build

New [build tools][] allows you to customize the bundle to your needs and possibly reduce size of the console even more than when using default settings. Check out "Building the console" section for more information.

## Introduction

API console is an web application created on top of the [Web Components specifications](https://www.webcomponents.org/introduction) and powered by the [Polymer library](https://www.polymer-project.org/). Familiarity with Polymer isn't necessary to use the console.

The following sections briefly describe how to build and use the console. For more information, see the [docs](docs) directory in this repository.

## Using the API console

Install our CLI tool globally using `-g` if possible:

```shell
$ sudo npm install -g api-console-cli
```

Generate API console from your RAML or OAS file:

```shell
$ api-console build -t "RAML 1.0" -a path/to/api.raml # works with remote files too
```

Preview the console:

```shell
$ api-console serve build/ --open
```

### Run as a standalone web-application

Recommended way of using API console is to build a standalone application that can be served from your server. Generated sources with `api-console-cli` is production ready bundle of the console ready to be served to your users. The application supports [Deep linking][deep linking], which allows you to share a link to a particular part of your API documentation. You can find a basic example of the standalone application on our [demo application][] web page.

To build the API Console as a standalone application use our [build tools][].

### Using API components

This is advanced option for developers to embed the console or one of it's components into existing web page.

API console is a web component. This mean it can be used in any web environments (browser, Chrome frame, Electron app etc). Also it can be mixed with any framework as it does not reference other frameworks.

This version of the console still works with `bower` as a dependency manager as it works with HTML imports. Next version will work with ES6 module imports which supports npm as a dependency management system.
This is a preview of the next version of API Console. Feel free to try it out and to file a bug report if necessary.

First, use [Bower][] to install the console and its dependencies:

```bash
$ bower install --save mulesoft/api-console
```

Next, include the element in your web page:

```html
<link rel="import" href="bower_components/api-console/api-console.html">
```

Finally use the HTML tag:

```html
<body>
<api-console narrow amf-model="{...}"></api-console>
</body>
```

See complete documentation about how to import sources into your web page in the [api console element docs][]. Also, if you are a developer you can check out [demo application source code][].

You can also build API Console as a embeddable HTML element using one of our [build tools][].

## API Console configuration options

Configuration options differ from the previous version. Because API Console is a (custom) HTML element its configuration is based on HTML attributes. You can pass values as an attribute value, or use a boolean option by simply setting the attribute. Configuration from JavaScript code is based on setting a JavaScript property as the attribute name on the element. If the attribute name contains dashes then make the property name [camel case][].

Example:

```html
<api-console append-headers="x-api-key: 1234" narrow></api-console>
```

An equivalent example is:

```javascript
var console = document.querySelector('api-console');
console.narrow = true;
console.appendHeaders = 'x-api-key: 1234';
```

See the full list of API Console configuration options in the [configuring the api console][] document.

## Build tools

A set of build tools is included to help you create API Console from the RAML file. Build tools are configured to produce a production optimized version of API Console. The build tools can generate both standalone and embeddable version of the console. You can also configure data source strategy (RAML, JSON or inline JSON as a data source).

The following build tools are available:

* The API console CLI
* Node modules
* `api-console-builder`
* `amf-client-js`

Depending on your needs you can choose whether you want to use a CLI tool or a node module.

Build tools can be helpful in the CI process to automate the documentation release cycle. See the [build tools][] documentation for more information and build strategies.

## Theming
API Console supports theming and comes with a default theme. You can create your own theme. For example, you can tweak the style of the console to match your corporate style guide.

Theming is based on CSS variables and CSS mixins. Basic concepts of using the variables and mixins are described in the [Polymer 2.0 styling][] documentation. You can check the [api-console-styles.html](api-console-styles.html) file to see the current theme definition, and then read the [theming documentation][] to learn how to create your own theme.

## CORS

Cross-origin resource sharing (CORS) allows sharing resources from one domain to other domains. Browsers block all requests to other domains but with a special set of headers authors can allow other domains to request a resource. For more information, see the [CORS Wiki][].

If your API does not allow CORS and you hosting your API documentation in different domain then API Console won't be able to make a request to an endpoint. API Console currently supports 3 ways of dealing with this issue:

- by installing the __API Console Chrome extension__
- by setting up a __proxy server__
- by handling HTTP requests from the hosting application

Read our [CORS guideline][] for more information about each of these solutions.
This branch is in active development and most probably changes daily. Update your branch regularly when previewing the next version.

## Preview and development

The API Console is a custom element that serves as a shell element for other custom web components. To develop the API Console most probably you'd have to develop one of over a hundred other web components that creates the console. All the elements are described in [the elements catalog][the elements catalogue].

1. Clone the element.
```
git clone https://github.com/mulesoft/api-console.git
Expand All @@ -149,50 +14,77 @@ cd api-console

2. Install dependencies.
```
bower install && npm i
npm i
```

3. Start local server.
```
npm start
```

4. If you are planning to parse own RAML/OAS file then additionally run this command to run AMF parsing service for the demo page:
```
npm staret
```
## Changelog (so far)

The default page is the element's documentation. Switch to demo to see a working example.
- Upgrade to final web components specification: replacing HTML imports with JavaScript modules
- Replacing Polymer with super lightweight, almost native, `LitElement`. This triggers a series of changes
- All dash-case attributes are now "no-dash", lowercase, web style attributes. For example old `redirect-uri` is now `redirecturi`. This is true for all properties used as HTML attribute. Properties names are the same.
- New templating engine. API Console now uses `lit-html` which is performant HTML templating system.
- Build process will be completely different. It is not yet ready, stay tuned.
- Redesigned base input controls. API console now uses own, material design based, basic UI input controls. It comes with 3 predefined styles:
- **Default** - Material design filled state
- **Outlined** - Material design outlined state controlled by `outlined` attribute
- **Anypoint** - Compatibility layer with the Anypoint platform. Controlled by `compatibility` attribute
- The request panel (aka try it) is now only renders editors that corresponds to the API data model. This means that, for example, if headers are not defined for given operation then headers panel is not rendered. Also, dropped support for tabs view for the editors and they are stacked now.
- Code mirror dependency requires some additional libraries that won't work inside JavaScript module. This means that those libraries have to be included into the web application before initializing the element. See `Code Mirror changes` section below
- API Console is now WCAG compliant. All components used to build the console passed [axe-core](https://github.com/dequelabs/axe-core) tests and therefore are fully accessible.
- The application and the component are now split into separate components. Use `api-console` for embedding the console inside existing web application and `api-console-app` for creating stand alone application.
- New demo pages. Preview the console with `npm start` command (run inside cloned repository) to see API console with various scenarios and configuration options.
- Removed any reference to CSS mixins (the `@apply` function). All styling options are now defined via CSS variables. Any styles defined for previous version of API console won't work.
- Minimised use of icons in favour regular buttons with labels.
- This release contains tones of bug fixes and improvements reported by the community and our customers ❤

You can also append the `/demo/` to the URL to switch to a demo page permanently.
Try this version of API console with your API and report an issue if anything is out of ordinary. We and the rest of the community will be grateful.

## Reporting issues and features requests
### Code Mirror changes

The API Console is open and we encourage the community to contribute to the project. However, it is very important to follow a few simple rules when you create an issue report or send a pull request.
**Note, the request panel won't run without this dependencies.**

See CONTRIBUTING.md for description of how to file issue report of feature request.
Code mirror is not ES6 ready. Their build contains AMD exports which is incompatible with native modules. Therefore the dependencies cannot be imported with the element but outside of it.
The component requires the following scripts to be ready before it's initialized (especially body and headers editors):

### Contributor's Agreement
```html
<script src="node_modules/jsonlint/lib/jsonlint.js"></script>
<script src="node_modules/codemirror/lib/codemirror.js"></script>
<script src="node_modules/codemirror/addon/mode/loadmode.js"></script>
<script src="node_modules/codemirror/mode/meta.js"></script>
<!-- Some basic syntax highlighting -->
<script src="node_modules/codemirror/mode/javascript/javascript.js"></script>
<script src="node_modules/codemirror/mode/xml/xml.js"></script>
<script src="node_modules/codemirror/mode/htmlmixed/htmlmixed.js"></script>
<script src="node_modules/codemirror/addon/lint/lint.js"></script>
<script src="node_modules/codemirror/addon/lint/json-lint.js"></script>
```

To contribute source code to this repository, read our [contributor's agreement](http://www.mulesoft.org/legal/contributor-agreement.html), and then execute it by running this notebook and following these instructions: [api-notebook.anypoint.mulesoft.com/notebooks/#380297ed0e474010ff43](https://api-notebook.anypoint.mulesoft.com/notebooks/#380297ed0e474010ff43)
CodeMirror's modes location. May be skipped if all possible modes are already included into the app.

## License
```html
<script>
/* global CodeMirror */
CodeMirror.modeURL = 'node_modules/codemirror/mode/%N/%N.js';
</script>
```

The API Console is shared under Common Public Attribution License Version 1.0 (CPAL-1.0).
You may want to add this dependencies to your build configuration to include it into the bundle.

See the LICENSE.md file for more information.

[deep linking]: https://en.wikipedia.org/wiki/Deep_linking
[demo application]: https://mulesoft.github.io/api-console
[demo application source code]: demo/standalone/index.html
[api console element docs]: docs/api-console-element.md
[build tools]: docs/build-tools.md
[configuring the api console]: docs/configuring-api-console.md
[theming documentation]: docs/theming.md
[camel case]: https://en.wikipedia.org/wiki/Camel_case
[polymer-cli]: https://www.polymer-project.org/1.0/docs/tools/polymer-cli
[Bower]: https://bower.io/
[Polymer 2.0 styling]: https://www.polymer-project.org/2.0/docs/devguide/custom-css-properties
[the elements catalogue]: https://elements.advancedrestclient.com/
[CORS Wiki]: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing
[CORS guideline]: docs/cors.md
### Dependencies for OAuth1 and Digest authorization methods

For the same reasons as for CodeMirror this dependencies are required for OAuth1 and Digest authorization panels to work.

```html
<script src="node_modules/cryptojslib/components/core.js"></script>
<script src="node_modules/cryptojslib/rollups/sha1.js"></script>
<script src="node_modules/cryptojslib/components/enc-base64-min.js"></script>
<script src="node_modules/cryptojslib/rollups/md5.js"></script>
<script src="node_modules/cryptojslib/rollups/hmac-sha1.js"></script>
<script src="node_modules/jsrsasign/lib/jsrsasign-rsa-min.js"></script>
```

0 comments on commit 3112cf3

Please sign in to comment.