See live example of the API console in our demo application.
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.
Great news! The next version of API console is here! The upgrade includes new design, new data model and and build process that allows to reduce the size of the console.
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 parsers.
* Currently, AMF supports RAML 0.8, RAML 1.0, OAS 2.0 and OAS 3.0. It can be extended by defining new vocabularies to support other API spec formats.
The new API console has undergone several rounds of testing and redesign to ensure that we offer best in class API documentation tools.
The revamped navigation allows to better understand the structure of the API, and users can navigate through the documentation faster.
The new documentation pages focus on presenting the API and not features of the app itself. This allows users to learn faster and be more productive.
New build tools allows you to customize the bundle to your needs and possibly reduce the size of the console even more than when using default settings. Check out the "Building the console" section for more information.
API console is a web application created on top of the Web Components specifications and powered by the Polymer library. 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 directory in this repository.
Install our CLI tool globally using -g if possible:
$ sudo npm install -g api-console-cliGenerate API console from your RAML or OAS file:
$ NODE_OPTIONS=--max_old_space_size=2048 api-console build -t "RAML 1.0" -a path/to/api.raml # works with remote files tooPreview the console:
$ api-console serve build/ --openRecommended 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, 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.
This is an advanced option for developers to embed the console or one of its 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.
First, use Bower to install the console and its dependencies:
$ bower install --save mulesoft/api-consoleNext, include the element in your web page:
<link rel="import" href="bower_components/api-console/api-console.html">Finally use the HTML tag:
<body>
<api-console narrow amf-model="{...}"></api-console>
</body>See the complete documentation on how to import sources into your web page in the api console element docs. Also, if you are a developer check out the demo application source code.
You can also build API Console as an embeddable HTML element using one of our build tools.
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 convert the property name to camel case.
Example:
<api-console append-headers="x-api-key: 1234" narrow></api-console>An equivalent example is:
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 configuring the api console.
A set of build tools is included to help you create API Console from the API specification 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 the 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-builderamf-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 documentation release cycles. See the build tools documentation for more information and build strategies.
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 file to see the current theme definition, and then read the theming documentation to learn how to create your own theme.
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 are hosting your API documentation in different domain, API Console won't be able to make a request to an endpoint. API Console currently supports three 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.
The API Console is a custom element that serves as a shell element for other custom web components. All the elements are described in the elements catalog.
- Clone the element.
git clone https://github.com/mulesoft/api-console.git
cd api-console
- Install polymer-cli and Bower.
sudo npm install -g bower polymer-cli
- Install dependencies.
bower install && npm i
- Serve the element.
polymer serve --open
- If you are planning to parse your own RAML/OAS file, run this command to run AMF parsing service for the demo page:
npm start
The default page is the element's documentation. Switch to demo to see a working example.
You can also append the /demo/ to the URL to switch to a demo page permanently.
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.
See CONTRIBUTING.md for description of how to file issue report of feature request.
To contribute source code to this repository, read our contributor's agreement, and then execute it by running this notebook and following these instructions: api-notebook.anypoint.mulesoft.com/notebooks/#380297ed0e474010ff43
The API Console is shared under Common Public Attribution License Version 1.0 (CPAL-1.0).
See the LICENSE.md file for more information.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent