diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..3e934048e --- /dev/null +++ b/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 diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 000000000..75ef3e033 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,527 @@ +RAML Tools License + +Common Public Attribution License Version 1.0 (CPAL-1.0) + +1. “Definitions” + +1.0.1 “Commercial Use” means distribution or otherwise making the Covered Code +available to a third party. + +1.1 “Contributor” means each entity that creates or contributes to the creation +of Modifications. + +1.2 “Contributor Version” means the combination of the Original Code, prior +Modifications used by a Contributor, and the Modifications made by that +particular Contributor. + +1.3 “Covered Code” means the Original Code or Modifications or the combination +of the Original Code and Modifications, in each case including portions thereof. + +1.4 “Electronic Distribution Mechanism” means a mechanism generally accepted in +the software development community for the electronic transfer of data. + +1.5 “Executable” means Covered Code in any form other than Source Code. + +1.6 “Initial Developer” means the individual or entity identified as the +Initial Developer in the Source Code notice required by Exhibit A. + +1.7 “Larger Work” means a work which combines Covered Code or portions thereof +with code not governed by the terms of this License. + +1.8 “License” means this document. + +1.8.1 “Licensable” means having the right to grant, to the maximum extent +possible, whether at the time of the initial grant or subsequently acquired, any +and all of the rights conveyed herein. + +1.9 “Modifications” means any addition to or deletion from the substance or +structure of either the Original Code or any previous Modifications. When +Covered Code is released as a series of files, a Modification is: + +A. Any addition to or deletion from the contents of a file containing Original +Code or previous Modifications. + +B. Any new file that contains any part of the Original Code or previous +Modifications. + +1.10 “Original Code” means Source Code of computer software code which is +described in the Source Code notice required by Exhibit A as Original Code, and +which, at the time of its release under this License is not already Covered Code +governed by this License. + +1.10.1 “Patent Claims” means any patent claim(s), now owned or hereafter +acquired, including without limitation, method, process, and apparatus claims, +in any patent Licensable by grantor. + +1.11 “Source Code” means the preferred form of the Covered Code for making +modifications to it, including all modules it contains, plus any associated +interface definition files, scripts used to control compilation and installation +of an Executable, or source code differential comparisons against either the +Original Code or another well known, available Covered Code of the Contributor’s +choice. The Source Code can be in a compressed or archival form, provided the +appropriate decompression or de-archiving software is widely available for no +charge. + +1.12 “You” (or “Your”) means an individual or a legal entity exercising rights +under, and complying with all of the terms of, this License or a future version +of this License issued under Section 6.1. For legal entities, “You” includes any +entity which controls, is controlled by, or is under common control with You. +For purposes of this definition, “control” means (a) the power, direct or +indirect, to cause the direction or management of such entity, whether by +contract or otherwise, or (b) ownership of more than fifty percent (50%) of the +outstanding shares or beneficial ownership of such entity. + +2. Source Code License. + +2.1 The Initial Developer Grant. + +The Initial Developer hereby grants You a world-wide, royalty-free, +non-exclusive license, subject to third party intellectual property claims: + +(a) under intellectual property rights (other than patent or trademark) +Licensable by Initial Developer to use, reproduce, modify, display, perform, +sublicense and distribute the Original Code (or portions thereof) with or +without Modifications, and/or as part of a Larger Work; and + +(b) under Patents Claims infringed by the making, using or selling of Original +Code, to make, have made, use, practice, sell, and offer for sale, and/or +otherwise dispose of the Original Code (or portions thereof). + +(c) the licenses granted in this Section 2.1(a) and (b) are effective on the +date Initial Developer first distributes Original Code under the terms of this +License. + +(d) Notwithstanding Section 2.1(b) above, no patent license is granted: 1) for +code that You delete from the Original Code; 2) separate from the Original Code; +or 3) for infringements caused by: i) the modification of the Original Code or +ii) the combination of the Original Code with other software or devices. + +2.2 Contributor Grant. + +Subject to third party intellectual property claims, each Contributor hereby +grants You a world-wide, royalty-free, non-exclusive license + +(a) under intellectual property rights (other than patent or trademark) +Licensable by Contributor, to use, reproduce, modify, display, perform, +sublicense and distribute the Modifications created by such Contributor (or +portions thereof) either on an unmodified basis, with other Modifications, as +Covered Code and/or as part of a Larger Work; and + +(b) under Patent Claims infringed by the making, using, or selling of +Modifications made by that Contributor either alone and/or in combination with +its Contributor Version (or portions of such combination), to make, use, sell, +offer for sale, have made, and/or otherwise dispose of: 1) Modifications made by +that Contributor (or portions thereof); and 2) the combination of Modifications +made by that Contributor with its Contributor Version (or portions of such +combination). + +(c) the licenses granted in Sections 2.2(a) and 2.2(b) are effective on the +date Contributor first makes Commercial Use of the Covered Code. + +(d) Notwithstanding Section 2.2(b) above, no patent license is granted: 1) for +any code that Contributor has deleted from the Contributor Version; 2) separate +from the Contributor Version; 3) for infringements caused by: i) third party +modifications of Contributor Version or ii) the combination of Modifications +made by that Contributor with other software (except as part of the Contributor +Version) or other devices; or 4) under Patent Claims infringed by Covered Code +in the absence of Modifications made by that Contributor. + +3. Distribution Obligations. + + + +3.1 Application of License. + +The Modifications which You create or to which You contribute are governed by +the terms of this License, including without limitation Section 2.2. The Source +Code version of Covered Code may be distributed only under the terms of this +License or a future version of this License released under Section 6.1, and You +must include a copy of this License with every copy of the Source Code You +distribute. You may not offer or impose any terms on any Source Code version +that alters or restricts the applicable version of this License or the +recipients’ rights hereunder. However, You may include an additional document +offering the additional rights described in Section 3.5. + +3.2 Availability of Source Code. + +Any Modification which You create or to which You contribute must be made +available in Source Code form under the terms of this License either on the same +media as an Executable version or via an accepted Electronic Distribution +Mechanism to anyone to whom you made an Executable version available; and if +made available via Electronic Distribution Mechanism, must remain available for +at least twelve (12) months after the date it initially became available, or at +least six (6) months after a subsequent version of that particular Modification +has been made available to such recipients. You are responsible for ensuring +that the Source Code version remains available even if the Electronic +Distribution Mechanism is maintained by a third party. + +3.3 Description of Modifications. + +You must cause all Covered Code to which You contribute to contain a file +documenting the changes You made to create that Covered Code and the date of any +change. You must include a prominent statement that the Modification is derived, +directly or indirectly, from Original Code provided by the Initial Developer and +including the name of the Initial Developer in (a) the Source Code, and (b) in +any notice in an Executable version or related documentation in which You +describe the origin or ownership of the Covered Code. + +3.4 Intellectual Property Matters + +(a) Third Party Claims. + +If Contributor has knowledge that a license under a third party’s intellectual +property rights is required to exercise the rights granted by such Contributor +under Sections 2.1 or 2.2, Contributor must include a text file with the Source +Code distribution titled “LEGAL” which describes the claim and the party making +the claim in sufficient detail that a recipient will know whom to contact. If +Contributor obtains such knowledge after the Modification is made available as +described in Section 3.2, Contributor shall promptly modify the LEGAL file in +all copies Contributor makes available thereafter and shall take other steps +(such as notifying appropriate mailing lists or newsgroups) reasonably +calculated to inform those who received the Covered Code that new knowledge has +been obtained. + +(b) Contributor APIs. + +If Contributor’s Modifications include an application programming interface and +Contributor has knowledge of patent licenses which are reasonably necessary to +implement that API, Contributor must also include this information in the LEGAL +file. + +(c) Representations. + +Contributor represents that, except as disclosed pursuant to Section 3.4(a) +above, Contributor believes that Contributor’s Modifications are Contributor’s +original creation(s) and/or Contributor has sufficient rights to grant the +rights conveyed by this License. + +3.5 Required Notices. + +You must duplicate the notice in Exhibit A in each file of the Source Code. If +it is not possible to put such notice in a particular Source Code file due to +its structure, then You must include such notice in a location (such as a +relevant directory) where a user would be likely to look for such a notice. If +You created one or more Modification(s) You may add your name as a Contributor +to the notice described in Exhibit A. You must also duplicate this License in +any documentation for the Source Code where You describe recipients’ rights or +ownership rights relating to Covered Code. You may choose to offer, and to +charge a fee for, warranty, support, indemnity or liability obligations to one +or more recipients of Covered Code. However, You may do so only on Your own +behalf, and not on behalf of the Initial Developer or any Contributor. You must +make it absolutely clear than any such warranty, support, indemnity or liability +obligation is offered by You alone, and You hereby agree to indemnify the +Initial Developer and every Contributor for any liability incurred by the +Initial Developer or such Contributor as a result of warranty, support, +indemnity or liability terms You offer. + +3.6 Distribution of Executable Versions. + +You may distribute Covered Code in Executable form only if the requirements of +Section 3.1-3.5 have been met for that Covered Code, and if You include a notice +stating that the Source Code version of the Covered Code is available under the +terms of this License, including a description of how and where You have +fulfilled the obligations of Section 3.2. The notice must be conspicuously +included in any notice in an Executable version, related documentation or +collateral in which You describe recipients’ rights relating to the Covered +Code. You may distribute the Executable version of Covered Code or ownership +rights under a license of Your choice, which may contain terms different from +this License, provided that You are in compliance with the terms of this License +and that the license for the Executable version does not attempt to limit or +alter the recipient’s rights in the Source Code version from the rights set +forth in this License. If You distribute the Executable version under a +different license You must make it absolutely clear that any terms which differ +from this License are offered by You alone, not by the Initial Developer, +Original Developer or any Contributor. You hereby agree to indemnify the Initial +Developer, Original Developer and every Contributor for any liability incurred +by the Initial Developer, Original Developer or such Contributor as a result of +any such terms You offer. + +3.7 Larger Works. + +You may create a Larger Work by combining Covered Code with other code not +governed by the terms of this License and distribute the Larger Work as a single +product. In such a case, You must make sure the requirements of this License are +fulfilled for the Covered Code. + +4. Inability to Comply Due to Statute or Regulation. + + + +If it is impossible for You to comply with any of the terms of this License with +respect to some or all of the Covered Code due to statute, judicial order, or +regulation then You must: (a) comply with the terms of this License to the +maximum extent possible; and (b) describe the limitations and the code they +affect. Such description must be included in the LEGAL file described in Section +3.4 and must be included with all distributions of the Source Code. Except to +the extent prohibited by statute or regulation, such description must be +sufficiently detailed for a recipient of ordinary skill to be able to understand +it. + +5. Application of this License. + + + +This License applies to code to which the Initial Developer has attached the +notice in Exhibit A and to related Covered Code. + +6. Versions of the License. + + + +6.1 New Versions. + +Socialtext, Inc. (“Socialtext”) may publish revised and/or new versions of the +License from time to time. Each version will be given a distinguishing version +number. + +6.2 Effect of New Versions. + +Once Covered Code has been published under a particular version of the License, +You may always continue to use it under the terms of that version. You may also +choose to use such Covered Code under the terms of any subsequent version of the +License published by Socialtext. No one other than Socialtext has the right to +modify the terms applicable to Covered Code created under this License. + +6.3 Derivative Works. + +If You create or use a modified version of this License (which you may only do +in order to apply it to code which is not already Covered Code governed by this +License), You must (a) rename Your license so that the phrases “Socialtext”, +“CPAL” or any confusingly similar phrase do not appear in your license (except +to note that your license differs from this License) and (b) otherwise make it +clear that Your version of the license contains terms which differ from the +CPAL. (Filling in the name of the Initial Developer, Original Developer, +Original Code or Contributor in the notice described in Exhibit A shall not of +themselves be deemed to be modifications of this License.) + +7. DISCLAIMER OF WARRANTY. + + + +COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN “AS IS” BASIS, WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT +LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF DEFECTS, MERCHANTABLE, +FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE +QUALITY AND PERFORMANCE OF THE COVERED CODE IS WITH YOU. SHOULD ANY COVERED CODE +PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL DEVELOPER, ORIGINAL +DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, +REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART +OF THIS LICENSE. NO USE OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER +THIS DISCLAIMER. + +8. TERMINATION. + + + +8.1 This License and the rights granted hereunder will terminate automatically +if You fail to comply with terms herein and fail to cure such breach within 30 +days of becoming aware of the breach. All sublicenses to the Covered Code which +are properly granted shall survive any termination of this License. Provisions +which, by their nature, must remain in effect beyond the termination of this +License shall survive. + +8.2 If You initiate litigation by asserting a patent infringement claim +(excluding declatory judgment actions) against Initial Developer, Original +Developer or a Contributor (the Initial Developer, Original Developer or +Contributor against whom You file such action is referred to as “Participant”) +alleging that: + +(a) such Participant’s Contributor Version directly or indirectly infringes any +patent, then any and all rights granted by such Participant to You under +Sections 2.1 and/or 2.2 of this License shall, upon 60 days notice from +Participant terminate prospectively, unless if within 60 days after receipt of +notice You either: (i) agree in writing to pay Participant a mutually agreeable +reasonable royalty for Your past and future use of Modifications made by such +Participant, or (ii) withdraw Your litigation claim with respect to the +Contributor Version against such Participant. If within 60 days of notice, a +reasonable royalty and payment arrangement are not mutually agreed upon in +writing by the parties or the litigation claim is not withdrawn, the rights +granted by Participant to You under Sections 2.1 and/or 2.2 automatically +terminate at the expiration of the 60 day notice period specified above. + +(b) any software, hardware, or device, other than such Participant’s +Contributor Version, directly or indirectly infringes any patent, then any +rights granted to You by such Participant under Sections 2.1(b) and 2.2(b) are +revoked effective as of the date You first made, used, sold, distributed, or had +made, Modifications made by that Participant. + +8.3 If You assert a patent infringement claim against Participant alleging that +such Participant’s Contributor Version directly or indirectly infringes any +patent where such claim is resolved (such as by license or settlement) prior to +the initiation of patent infringement litigation, then the reasonable value of +the licenses granted by such Participant under Sections 2.1 or 2.2 shall be +taken into account in determining the amount or value of any payment or license. + +8.4 In the event of termination under Sections 8.1 or 8.2 above, all end user +license agreements (excluding distributors and resellers) which have been +validly granted by You or any distributor hereunder prior to termination shall +survive termination. + +9. LIMITATION OF LIABILITY. + + + +UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT (INCLUDING +NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE INITIAL DEVELOPER, ORIGINAL +DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE, OR ANY +SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY INDIRECT, +SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, +WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER +FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN +IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS +LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL +INJURY RESULTING FROM SUCH PARTY’S NEGLIGENCE TO THE EXTENT APPLICABLE LAW +PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR +LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS EXCLUSION AND +LIMITATION MAY NOT APPLY TO YOU. + +10. U.S. GOVERNMENT END USERS. + + + +The Covered Code is a “commercial item,” as that term is defined in 48 C.F.R. +2.101 (Oct. 1995), consisting of “commercial computer software” and “commercial +computer software documentation,” as such terms are used in 48 C.F.R. 12.212 +(Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through +227.7202-4 (June 1995), all U.S. Government End Users acquire Covered Code with +only those rights set forth herein. + +11. MISCELLANEOUS. + + + +This License represents the complete agreement concerning subject matter hereof. +If any provision of this License is held to be unenforceable, such provision +shall be reformed only to the extent necessary to make it enforceable. This +License shall be governed by California law provisions (except to the extent +applicable law, if any, provides otherwise), excluding its conflict-of-law +provisions. With respect to disputes in which at least one party is a citizen +of, or an entity chartered or registered to do business in the United States of +America, any litigation relating to this License shall be subject to the +jurisdiction of the Federal Courts of the Northern District of California, with +venue lying in Santa Clara County, California, with the losing party responsible +for costs, including without limitation, court costs and reasonable attorneys’ +fees and expenses. The application of the United Nations Convention on Contracts +for the International Sale of Goods is expressly excluded. Any law or regulation +which provides that the language of a contract shall be construed against the +drafter shall not apply to this License. + +12. RESPONSIBILITY FOR CLAIMS. + + + +As between Initial Developer, Original Developer and the Contributors, each +party is responsible for claims and damages arising, directly or indirectly, out +of its utilization of rights under this License and You agree to work with +Initial Developer, Original Developer and Contributors to distribute such +responsibility on an equitable basis. Nothing herein is intended or shall be +deemed to constitute any admission of liability. + +13. MULTIPLE-LICENSED CODE. + + + +Initial Developer may designate portions of the Covered Code as +Multiple-Licensed. Multiple-Licensed means that the Initial Developer permits +you to utilize portions of the Covered Code under Your choice of the CPAL or the +alternative licenses, if any, specified by the Initial Developer in the file +described in Exhibit A. + +14. ADDITIONAL TERM: ATTRIBUTION + +(a) As a modest attribution to the organizer of the development of the Original +Code (“Original Developer”), in the hope that its promotional value may help +justify the time, money and effort invested in writing the Original Code, the +Original Developer may include in Exhibit B (“Attribution Information”) a +requirement that each time an Executable and Source Code or a Larger Work is +launched or initially run (which includes initiating a session), a prominent +display of the Original Developer’s Attribution Information (as defined below) +must occur on the graphic user interface employed by the end user to access such +Covered Code (which may include display on a splash screen), if any. The size of +the graphic image should be consistent with the size of the other elements of +the Attribution Information. If the access by the end user to the Executable and +Source Code does not create a graphic user interface for access to the Covered +Code, this obligation shall not apply. If the Original Code displays such +Attribution Information in a particular form (such as in the form of a splash +screen, notice at login, an “about” display, or dedicated attribution area on +user interface screens), continued use of such form for that Attribution +Information is one way of meeting this requirement for notice. + +(b) Attribution information may only include a copyright notice, a brief +phrase, graphic image and a URL (“Attribution Information”) and is subject to +the Attribution Limits as defined below. For these purposes, prominent shall +mean display for sufficient duration to give reasonable notice to the user of +the identity of the Original Developer and that if You include Attribution +Information or similar information for other parties, You must ensure that the +Attribution Information for the Original Developer shall be no less prominent +than such Attribution Information or similar information for the other party. +For greater certainty, the Original Developer may choose to specify in Exhibit B +below that the above attribution requirement only applies to an Executable and +Source Code resulting from the Original Code or any Modification, but not a +Larger Work. The intent is to provide for reasonably modest attribution, +therefore the Original Developer cannot require that You display, at any time, +more than the following information as Attribution Information: (a) a copyright +notice including the name of the Original Developer; (b) a word or one phrase +(not exceeding 10 words); (c) one graphic image provided by the Original +Developer; and (d) a URL (collectively, the “Attribution Limits”). + +(c) If Exhibit B does not include any Attribution Information, then there are +no requirements for You to display any Attribution Information of the Original +Developer. + +(d) You acknowledge that all trademarks, service marks and/or trade names +contained within the Attribution Information distributed with the Covered Code +are the exclusive property of their owners and may only be used with the +permission of their owners, or under circumstances otherwise permitted by law or +as expressly set out in this License. + +15. ADDITIONAL TERM: NETWORK USE. + + + +The term “External Deployment” means the use, distribution, or communication of +the Original Code or Modifications in any way such that the Original Code or +Modifications may be used by anyone other than You, whether those works are +distributed or communicated to those persons or made available as an application +intended for use over a network. As an express condition for the grants of +license hereunder, You must treat any External Deployment by You of the Original +Code or Modifications as a distribution under section 3.1 and make Source Code +available under Section 3.2. + + + + + +EXHIBIT A + + + +“The contents of this file are subject to the Common Public Attribution License +Version 1.0 (the “License”); you may not use this file except in compliance with +the License. You may obtain a copy of the License at +https://github.com/raml-org. The License is based on the Mozilla Public License +Version 1.1 but Sections 14 and 15 have been added to cover use of software over +a computer network and provide for limited attribution for the Original +Developer. In addition, Exhibit A has been modified to be consistent with +Exhibit B. + +Software distributed under the License is distributed on an “AS IS” basis, +WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the +specific language governing rights and limitations under the License. + +The Original Code is the JSNotebook, API Designer, and API Console. + +The Initial Developer of the Original Code is MuleSoft. Copyright (c) 2013 +MuleSoft. All Rights Reserved. + + + +EXHIBIT B. Attribution Information Attribution Copyright Notice: Copyright (c) +2013 MuleSoft, Inc. + +Attribution Phrase (not exceeding 10 words): Powered by MuleSoft for RAML. +Attribution URL: http://www.MuleSoft.org + +Graphic Image provided in the Covered Code as file: + +http://www.mulesoft.com/sites/all/themes/mulesoft/images/elements/powered-by-mulesoft.png diff --git a/README.md b/README.md index bad3a8226..acee4c3d4 100644 --- a/README.md +++ b/README.md @@ -4,667 +4,148 @@ An API console for RAML (Restful Api Modeling Language) documents. The RAML Cons ## Introduction -The API console is a single HTML element build on top of the [Web Components specifications](https://www.webcomponents.org/introduction) and powered by the [Polymer library](https://www.polymer-project.org/). Knowledge about how polymer works won't be necessary for using the console. +The API console is a single HTML element build on top of the [Web Components specifications](https://www.webcomponents.org/introduction) and powered by the [Polymer library](https://www.polymer-project.org/). Knowledge about how Polymer works won't be necessary when using the console. -The element can be used to display documentation for the API defined in RAML. Basic usage of the element is as simple as using any other HTML element: +## 1. Using the API console -```html - -``` - -See full usage documentaiton [below](#usage). - -## Preview and development - -1. Clone the element: -``` -git clone https://github.com/mulesoft/api-console.git -cd api-console -``` - -2. Checkout develop version -``` -git checkout develop -``` +The API console comes with two flavors: as a **HTML element** and as a **standalone application**. Depending on your use case you should choose the best option for your users. -3. Install [polymer-cli](https://www.polymer-project.org/1.0/docs/tools/polymer-cli) and Bower -``` -sudo npm install -g bower polymer-cli -``` +### Standalone application -4. Install dependencies -``` -bower install -``` +API Console as a standalone application should be used to display the documentation for your API as a web page. -5. Serve the element -``` -polymer serve --open -p 8080 -``` +The application will support routing ([Deep linking][deep linking]) and it will render the documentation full screen. -Default page is the element documentation. Switch to demo to see working example. +Also, if needed, the application can include RAML parser so it can accept the RAML file and transform its content into internal data model. See [Optimization](#optimisation-options) section below for more information. -You can also append the `/demo/` to the URL to switch to demo page permanently. +Basic example of the standalone application you will find in [demo application] inside this repository. -## Usage +### HTML element -### Install +The API Console was build on top of new Web Components specification. When you include sources of the console into your web application it will register a new HTML element, the `` element, that can be used as any other element on your page or web application. This means that you can embed the console into your blog post or as a part of press release and your users will be able to get know your API without being redirected to another web page. -Install the console as a dependency of your project. We use [bower](https://bower.io/) for this. +For example: -``` -bower install --save mulesoft/api-console#4.0.0 +```html + ``` -Bower will also install dependencies of the console. +See full usage documentation and how to import sources into your web page in the [api console element docs]. -### Import to the web page +## 2. Optimisation options -For the element to be recognized by the browser as a new HTML element you have to include it in the page source. +The API Console displays a documentation for RAML definition. It means that it must perform some heavy duty computations to transform RAML data into JavaScript object and this takes time. There are, however, few options to optimise loading time of the API console. It depends on your use case. -```html - -``` +### RAML data source -### Use the HTML tag +If your API is under active development and changes often, you may want to consider using the RAML file hosted on a server as a data source. The API console application will then parse RAML file using RAML JavaScript parser and use the parser output as a data source. It will take some time during console's load time but you will always display your APIs newest version. -```html - - - -``` +Because this use case requires to include more custom HTML elements it's not suitable for the standalone version. Other options would be a better fit. -How to pass RAML data to the element is described below in the [Passing the RAML data](#passing-the-raml-data) section. +### JSON data source -A full list of available configurations for the `api-console` element can be found inside section [Element configuration (attributes)](#element-configuration-attributes). +This is a good choice if your API doesn't change often or if you are using our [build tools] in your CI process. In this case you can generate a JSON file from the RAML and use it as a data input in the `` element. -### Setup polyfills +This option will significantly reduce the API Console load time. It is also suitable for both standalone application and the HTML element. -This step is not required if you targeting modern browsers only! +### JSON inlined in the page source -Web components are based on four new specifications (Custom elements, shadow DOM, HTML imports and HTML template) that are not fully supported in legacy browsers (like IE). Also, browser vendors still discussing the HTML imports specification so it's not implemented in Edge and Firefox yet. +This option gives you the fastest load time but may increase initial page weight. It is the same option as the JSON data source but the JSON data are not kept in separate JSON file but the data are included in the page source as a JavaScript object. -If you planning to target these browsers you must include a polyfill for Web Components. The polyfill library is already included into your project (giving you have installed the element using `bower`). +You should use this if your API changes rarely or never. Every change to source RAML file would require regenerating the whole page. Though, it can be automated with our [build tools]. -Example use of the polyfill library: +## 3. API Console configuration options -```html - - ... - - -... -``` +Configuration options differs from previous version. Because the API console is a (custom) HTML element it's configuration is based on HTML attributes. You can pass values as an attribute value or set 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 the property name should be [camel cased]. -### Full example +Example: ```html - - - - - - - - - - - - + ``` -## Passing the RAML data - -### Before you begin: asynchronous environment +which is equivalent of: -Web components are asynchronous by nature. It means that elements import, -registering them in the DOM and finally initializing the element is made asynchronously. Therefore you can't expect the element to work right after loading the page (as regular HTML elements does). Consider following example: - -```html - - +```javascript +var console = document.querySelector('api-console'); +console.narrow = true; +console.appendHeaders = 'x-api-key: 1234'; ``` -Running this code on page load will throw a `TypeError` with the message: `parser.loadApi is not a function`. +Full list of the API console configuration options can be found in the [configuring the api console] document. -It's because at the time of execution of the script block the browser knows nothing about the `raml-js-parser` element. At the time it is an instance of `HTMLUnknownElement`. +## 4. Build tools -The browser hast to execute the import first and then the Polymer library has to register the HTML element called `raml-js-parser`. +The API Console comes with a set of build tools that will help you create the API console from the RAML file. Build tools are configured to produce a production optimized version of the 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). -To run the code properly you have to listen for the `WebComponentsReady` event. It's fired when the elements are ready to use. +Available build tools are the `api-console` CLI and node modules: `api-console-builder` and `raml-json-enhance-node`. Depending on your needs you can choose whether you want to use a CLI tool or a node module. -```html - - -``` +Build tools can be helpful in the CI process to automate documentation release cycle. See the [build tools] documentation for more information and build strategies. -### JSON instead of RAML +## 5. Theming -The API console web component requires JavaScript object produced by the [raml-js-parser](https://elements.advancedrestclient.com/elements/raml-js-parser) and [raml-js-enhancer](https://elements.advancedrestclient.com/elements/raml-json-enhance) elements. Parsing and enhancing RAML is not part of the `api-console` element and must be performed separately as described below. +The API console support theming. By default it comes with it's own styling but you can create your own theme and style the console to match your corporate style guide. -Use the `raml-js-parser` element to parse YAML data or to download RAML from remote location. __Note__: You may also use our [raml-js-parser-2](https://github.com/raml-org/raml-js-parser-2) node library as it gives the same output. +Theming is based on CSS variables and CSS mixins. Basic concepts of using the variables and mixins are described in [Polymer 1.0 styling] documentation. You can check the [api-console-styles.html](api-console-styles.html) file to see current theme definition and then read [theming documentation] to learn how to create your own theme. -Then you must use the `raml-js-enhancer` element to produce data output that is recognizable by the `api-console`. The enhancer creates a common data structure and expands RAML types (flattens it's structure so a type doesn't have complex inheritance structure). Elements used to build the API Console expects the JSON object to contain complete data about a method / endpoint / type / security scheme and so on. They will not look into nor have access to the data in the root of RAML definition. The enhancer replaces objects into arrays (adding a `key` property to each item) so it can be used in a templating systems. Also `example` property of the RAML is always translated to `examples` array. Finally the enhancer creates `fullUrl` property on each HTTP method so the console don't need to compute it each time you open the documentation page. +## 6. Preview and development -#### Example: parsing and enhancing RAML as an input for the console +The API Console is a custom element that serves as a shell element for other custom web components. It means that 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 catalogue]. -```html - - - +1. Clone the element: ``` - -The parsing and enhancing costs a lot depending on RAML structure and number of files included. Therefore it is a good idea to do it once and cache the results. Then, when the user visit the page again restore cached JSON object and pass it as the `api-console` parameter (see below). - -### Setting RAML data as an HTML attribute - -The basic method to tell the API console what to display is to use the `raml` attribute. It accepts the JavaScript object produced by the parser and the enhancer described above. - -```html - - +git clone https://github.com/mulesoft/api-console.git +cd api-console ``` -The `` element also have a convenient `json-file` attribute that you can set to point to a file containing the parsed and enhanced JSON data. - -```html - +2. Checkout latest version ``` - -### Using RAML aware to pass the data - -The API console uses the [raml-aware](https://elements.advancedrestclient.com/elements/raml-aware) element internally. -It can be used to pass the RAML data to the console if direct access to the -element is not possible. This way the RAML data can be set for the element even -if the elements don't have direct access to each others (e.g. in shadow DOM). - -See the [raml-aware documentation](https://elements.advancedrestclient.com/elements/raml-aware) page for more details. - -#### Example - -```html - - +git checkout release/4.0.0 ``` -```javascript -window.addEventListener('raml-json-enhance-ready', function(e) { - var aware = document.querySelector('raml-aware'); - aware.raml = e.detail.json; -}); -parser.loadApi(urlToApi); +3. Install [polymer-cli] and [Bower]. ``` - -## Full web app example - -```html - - - - - - My API documentation - - - - - - - - - - - +sudo npm install -g bower polymer-cli ``` -## Element configuration (attributes) - -| Attribute | Description | Type | -| --- | --- | ---| -| `raml` | The JavaScript object or equivalent JSON object representing the RAML structure as a JavaScript object. | `Object or String` | -| `json-file` | Path to a file with JSON data that should be read and contents of it should be set to the `raml` attribute | `String` | -| `path` | Currently selected path in the view. See section [Controlling the view ](#controlling-the-view) for more information. | `String` | -| `aware` | If passing data by using the [raml-aware](https://elements.advancedrestclient.com/elements/raml-aware) element, it is the name as the `scope` attribute used in the aware. | `String` | -| `page` | Currently selected top level view of the console. It can be either `docs` or `request`. The later is the "try it screen". | `String` | -| `narrow` | By setting this attribute it will tell the API console to render a "narrow" view. This is a mobile like view (navigation is hidden in a drawer, some views are simplified for narrow screens) that will be presented event if the screen size is wide. This is helpful when inserting the element as a sidebar of your web page. Node that the `narrow` property will be set automatically on mobile devices | `Boolean` | -| `append-headers` | Forces the console to send specific list of headers, overriding user input if needed. | `String` | -| `proxy` | Sets the proxy URL for the HTTP requests sent from the console. If set all URLs will be altered before sending the data to a transport library bu prefixing the URL with this value | `String` -| `proxyEncodeUrl` | If required by the `proxy` the URL will be URL encoded. | `Boolean` | -| `noTryIt` | Disables the "try it" button in the method documentation view. The request editor and the response viewer is still available but you must open it programmatically setting `page` proerty to ` request` | `Boolean` | -| `manualNavigation` | Disables navigation in the drawer and renders the navigation full screen, when requested. This is ideal to use in the narrow layouts together with `narrow` property. | `Boolean` | -| `navigationOpened` | If set and `manualNavigation` is used then it will open / close the full screen navigation. | `Boolean` | - -## Styling - -The main stylesheet for the element is the `api-console-styles.html` file that resists in this repo. -The stylesheet contains CSS variables and mixins definitions that are used by the inner elements. -Styles documentation for any element used in the console can be find in it's documentation page in the -[elements catalog](https://elements.advancedrestclient.com/). - -Theming is currently not supported. - -## Controlling the view - -The `` element includes the UI for the user and can be controlled from within the -element. However it exposes few properties that can be used to control element's behavior programmatically. - -For example `path` property can be used to control to navigate through the RAML structure. -So, to display a request form for a particular endpoint of the API you can set a `path` property to: -```html - +4. Install dependencies ``` -Example above will display second method from first resource in the resources tree. -You can set attribute `display` to `request` to display a request panel for this method. By default -it is set to `docs`. - -## CORS - -There's no easy way to deal with CORS. In the API Console ecosystem there is an extension for Chrome -(and soon for Firefox) which will proxy the request without CORS limitations. The user, when using -selected browsers) will see the install extension banner in the request editor. After installing the -extension all traffic from the console will be redirected to the extension to get the endpoint -response. -The console listens for the `api-console-extension-installed` event that is fired from the -extension's content script. Once received the console will send an event to the extension -when the user make the HTTP request. The element responsible for the communication with the extension -is [api-console-ext-comm](https://elements.advancedrestclient.com/elements/api-console-ext-comm). - -Other ways to deal with CORS are coming. File an issue report in the repo if you can help with -this issue. - -## Using proxy server - -One of ways to deal with CORS is to tell the API console to pass the request through a proxy. -For this you can use `proxy` attribute. Once set then every request made by the console will be -passed through the proxy. - -When using proxy, the request URL will be altered before sending it to a transport library (possibly -the XHR call) by prefixing the URL with proxy value. - -```html - +bower install ``` -With this configuration a request made to `http://domain.com/path/?query=some+value` endpoint will -become `https://api.proxy.com/api/proxy/http://domain.com/path/?query=some+value`. - -Don't forget to add trailing '/' to the path or produced URL will be invalid. - -If the proxy require to set the URL as a query parameter then `proxy` attribute should end with -parameter name and `=` sign: - -```html - +5. Serve the element +``` +polymer serve --open -p 8080 ``` -In this case be sure to set `proxy-encode-url` attribute which will tell the console to URL encode -the URL before appending it ti the final URL - -With this configuration a request made to `http://domain.com/path/?query=some+value` endpoint will -become `https://api.proxy.com/api/proxy/?url=http%3A%2F%2Fdomain.com%2Fpath%2F%3Fquery%3Dsome%2Bvalue`. - -The proxy URL won't be visible by the user and the user can't do anything to change the behavior -until your application don't support proxy change in the UI. - -### Handling the HTTP request by the hosting website / application - -When a user runs the request from the "try it" screen the API Console will send the `api-console-request` custom event. If your application can handle transport for the HTTP request (by providing proxy or other solution) you should listen for this event and cancel it by calling `event.preventDefault()`. -If the event was cancelled then the API Console will listen for the `api-console-response` custom -event that should contain response details. Otherwise the console will use build in fallback function to get the resource using Fetch API / XHR. - -#### api-console-request custom event - -Event's `detail` object will contain following properties - -Property | Type | Description -----------------|-------------|---------- -`url` | String | The request URL -`method` | String | The HTTP method -`headers` | String | HTTP headers string to send with the message -`payload` | String | Body to send - -#### api-console-response +Default page is the element's documentation. Switch to demo to see working example. -This event must be fired when the hosting app finish the request. It must contain generated Request -and Response object as defined in the [Fetch specification](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch). The API console has polyfill for the Fetch API included. +You can also append the `/demo/` to the URL to switch to demo page permanently. -Property | Type | Description -----------------|-------------|---------- -`request` | Object | The request object as defined in the Fetch API spec. -`response` | Object | The response object as defined in the Fetch API spec. -`isXhr` | Boolean | Default to `true`. Indicated if the transport method doesn't support advanced timings and redirects information. See [request-panel](https://elements.advancedrestclient.com/elements/raml-request-panel) documentation for detailed description. -`error` | Error | When the request / response is errored (`request.ok` equals `false`) then the error object should be set with the human readable message that will be displayed to the user. +## 7. Reporting issues and features requests -#### Example with handling request / response events +The API Console and the Advanced REST client 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. -```javascript -// Start time of executing the request -var startTime; -// Initial request data passed by the event. -var requestData; -/** - * Creates a Headers object based on the HTTP headers string. - * - * @param {String} headers HTTP headers. - * @return {Headers} Parsed headers object. - */ -createHeaders: function(headers) { - if (!headers) { - return new Headers(); - } - var result = new Headers(); - var list = headers.split('\n').map(function(line) { - var _parts = line.split(':'); - var _name = _parts[0]; - var _value = _parts[1]; - _name = _name ? _name.trim() : null; - _value = _value ? _value.trim() : null; - if (!_name || !_value) { - return null; - } - return { - name: _name, - value: _value - }; - }).filter(function(item) { - return !!item; - }); - list.forEach(function(item) { - result.append(item.name, item.value); - }); - return result; -} -/** - * Creates a request object from the event's request data. - * - * @param {Object} data Latest request data as in the `api-console-request` object event. - * @return {Request} The Request object. - */ -function createRequest(data) { - var init = { - method: data.method, - mode: 'cors' - }; - if (data.headers) { - init.headers = createHeaders(data.headers); - } - if (['GET', 'HEAD'].indexOf(data.method) !== -1) { - data.payload = undefined; - } else { - if (data.payload) { - init.body = data.payload; - } - } - return new Request(data.url, init); -} -/** - * Creates a response object from the response data. - * If the response is invalid then returned Response object will be errored. - * - * @param {XMLHttpRequest} xhr The XHR object used to make a connection. - * @return {Response} The response object. - */ -function createResponse(xhr) { - var status = xhr.status; - if (!status || status < 200) { - return Response.error(); - } - var init = { - status: status, - statusText: xhr.statusText - }; - var headers = xhr.getAllResponseHeaders(); - if (headers) { - init.headers = createHeaders(headers); - } - try { - return new Response(xhr.responseText, init); - } catch (e) { - return Response.error(); - } -} -// General error handler. -function errorHandler(e) { - var loadTime = performance.now() - startTime; - var request = createRequest(requestData); - var detail = { - request: request, - response: Response.error(), - loadingTime: loadTime, - isXhr: true, - error: new Error('Resource is unavailable') - }; - var event = new CustomEvent('api-console-response', { - cancelable: false, - bubbles: true, - composed: true, - detail: detail - }); - document.body.dispatchEvent(event); -} -// Handler for load event -function loadHandler(e) { - var loadTime = performance.now() - startTime; - var request = createRequest(requestData); - var response = createResponse(e.target); - var detail = { - request: request, - response: response, - loadingTime: loadTime, - isXhr: true - }; - if (!response.ok) { - detail.error = new Error('Resource is unavailable'); - } - var event = new CustomEvent('api-console-response', { - cancelable: false, - bubbles: true, - composed: true, - detail: detail - }); - document.body.dispatchEvent(event); -} -// Handler to the event, sends the request -function consoleRequestHandler(e) { - requestData = e.detail; - var xhr = new XMLHttpRequest(); - xhr.open(requestData.method, requestData.url, true); - if (requestData.headers) { - requestData.headers.split('\n').forEach(function(header) { - var data = header.split(':'); - var name = data[0].trim(); - var value = ''; - if (data[1]) { - value = data[1].trim(); - } - try { - xhr.setRequestHeader(name, value); - } catch (e) { - console.log('Can\'t set header ' + name ' in the XHR call.'); - } - }); - } - xhr.addEventListener('load', loadHandler); - xhr.addEventListener('error', errorHandler); - xhr.addEventListener('timeout', errorHandler); - try { - startTime = performance.now(); - xhr.send(requestData.payload); - } catch (e) { - errorHandler(e); - } -} -window.addEventListener('api-console-request', consoleRequestHandler); -``` +Please, see CONTRIBUTING.md for description of how to file issue report of feature request. -## Sizing +### Contributor's Agreement -The `api-console` must either be explicitly sized, or contained by the explicitly -sized parent. Parent container also has to be positioned relatively -(`position: relative` CSS property). "Explicitly sized", means it either has -an explicit CSS height property set via a class or inline style, or else is -sized by other layout means (e.g. the flex layout or absolute positioning). +To contribute source code to this repository, please read our [contributor's agreement](http://www.mulesoft.org/legal/contributor-agreement.html), and then execute it by running this notebook and following the instructions: https://api-notebook.anypoint.mulesoft.com/notebooks/#380297ed0e474010ff43 -## Forcing the API Console to send a specific list of headers +## 8. License -You can force the API Console to send a specific list of headers for each request made by it. To -do this set the `append-headers` attribute. It should contain a HTTP headers string. -If the user declared a header that is declared in the `append-headers` attribute then user value -will be overridden. Otherwise headers will be appended to the headers string. +The API console is shared under Common Public Attribution License Version 1.0 (CPAL-1.0). -Use "\n" string to set a new line for the headers string. +See the LICENSE.md file for more information. -``` - -``` +[deep linking]: https://en.wikipedia.org/wiki/Deep_linking +[demo application]: demo/api.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 cased]: 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 1.0 styling]: https://www.polymer-project.org/1.0/docs/devguide/styling +[the elements catalogue]: https://elements.advancedrestclient.com/ diff --git a/changelog.md b/changelog.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..6ed4a8676 --- /dev/null +++ b/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) diff --git a/docs/api-console-element.md b/docs/api-console-element.md new file mode 100644 index 000000000..2253014f1 --- /dev/null +++ b/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 + +``` + +3) Use the HTML tag + +```html + + + +``` + +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 + + + + + + My API documentation + + + + + + + + +``` +[bower]: https://bower.io/ diff --git a/docs/bower.json b/docs/bower.json deleted file mode 100644 index 5befee761..000000000 --- a/docs/bower.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "name": "polymer-starter-kit", - "authors": [ - "The Polymer Authors" - ], - "private": true, - "dependencies": { - "app-layout": "PolymerElements/app-layout#^0.10.0", - "app-route": "PolymerElements/app-route#^0.9.0", - "iron-flex-layout": "PolymerElements/iron-flex-layout#^1.0.0", - "iron-icon": "PolymerElements/iron-icon#^1.0.12", - "iron-iconset-svg": "PolymerElements/iron-iconset-svg#^1.0.0", - "iron-localstorage": "PolymerElements/iron-localstorage#^1.0.0", - "iron-media-query": "PolymerElements/iron-media-query#^1.0.0", - "iron-pages": "PolymerElements/iron-pages#^1.0.0", - "iron-selector": "PolymerElements/iron-selector#^1.0.0", - "paper-icon-button": "PolymerElements/paper-icon-button#~1.1.0", - "polymer": "Polymer/polymer#^1.6.0", - "raml-js-parser": "advanced-rest-client/raml-js-parser#^2.0.0", - "raml-json-enhance": "advanced-rest-client/raml-json-enhance#^0.1.4", - "raml-aware": "advanced-rest-client/raml-aware#^1.0.2", - "paper-toast": "PolymerElements/paper-toast#^1.3.0", - "paper-spinner": "PolymerElements/paper-spinner#^1.2.1", - "raml-request-panel": "advanced-rest-client/raml-request-panel#^0.1.0", - "raml-documentation-panel": "advanced-rest-client/raml-documentation-panel#^2.0.9", - "paper-progress": "PolymerElements/paper-progress#^1.0.11", - "paper-button": "PolymerElements/paper-button#^1.0.14", - "arc-icons": "advanced-rest-client/arc-icons#^1.0.10", - "paper-dialog": "PolymerElements/paper-dialog#^1.1.0", - "paper-input": "PolymerElements/paper-input#^1.1.22", - "response-view": "advanced-rest-client/response-view#^0.1.1", - "fetch-polyfill": "advanced-rest-client/fetch-polyfill#^0.1.1", - "api-console-ext-comm": "advanced-rest-client/api-console-ext-comm#^0.1.1", - "anypoint-styles": "advanced-rest-client/anypoint-styles#^0.1.2" - }, - "devDependencies": { - "web-component-tester": "^4.0.0" - } -} diff --git a/docs/build-tools.md b/docs/build-tools.md new file mode 100644 index 000000000..270646cb8 --- /dev/null +++ b/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); +}); +``` diff --git a/docs/configuring-api-console.md b/docs/configuring-api-console.md new file mode 100644 index 000000000..e97417e0e --- /dev/null +++ b/docs/configuring-api-console.md @@ -0,0 +1,85 @@ +# API Console configuration options + +Configuration options differs from previous version. Because the API console is now a (custom) HTML element it's configuration is based on HTML attributes. + +You can pass a configuration option as follows: + +```html + + +``` + +which is equivalent of: + +```javascript +// Configuring the API Console using JavaScript properties. +var console = document.querySelector('api-console'); +console.narrow = true; +console.appendHeaders = 'x-api-key: 1234'; +``` + +**Boolean attributes** can be set by simply adding an attribute without any value or passing empty value (`attrobute=""`) which may be required by some HTML validators. Lack of attribute means it's value equals `false`. + +**Other attributes** can be configured by setting a value to the attribute as in the example above. + +Note that attributes that contains dash sign are camelCased when using Javascript access to the property. In the example above the `append-headers` HTML attribute becomes `appendHeaders` JavaScript property. + +Table below describes HTML attributes. If you are accessing JavaScript properties you have to [camel case] them. + +| Attribute | Description | Type | +| --- | --- | ---| +| `raml` | The JavaScript object representing the RAML structure as a JavaScript object. This is a result of parsing the RAML using Mulesoft's [RAML parser] and transformed using RAML enhancer. See [Passing RAML data](passing-raml-data.md) documentation for more information. | `Object or String` | +| `json-file` | URL to a file with JSON data that should be read and contents of it should be set to the `raml` attribute. See [build tools](build-tools.md) documentation for more information. | `String` | +| `path` | Currently selected path in the view. See section [Controlling the view ](#controlling-the-view) section below for more information. | `String` | +| `aware` | If passing the RAML data with the [raml-aware] element, it is the value of the `scope` attribute used in the aware. | `String` | +| `page` | Currently selected top level view of the console. It can be either `docs` or `request`. The later is the "try it" screen. | `String` | +| `narrow` | By setting this attribute it will tell the API console to render a "narrow" view. This is a mobile like view (navigation is hidden in a drawer, some views are simplified for narrow screens) that will be presented even if the screen is wide enough to display the full console. This is helpful when inserting the element as a sidebar of your web page. Note that the `narrow` property will be set automatically on mobile devices. | `Boolean` | +| `append-headers` | Forces the console to send specific list of headers, overriding user input if needed. As the attribute value pass a HTTP headers string separating lines with the `\n` character. Example: `x-api-token: abc\nx-other-headers: header value`. | `String` | +| `proxy` | Sets the proxy URL for the HTTP requests sent from the console. If set all URLs will be altered before sending the data to a transport library by prefixing the URL with this value | `String` +| `proxy-encodeUrl` | If required by the `proxy` the URL will be URL encoded. | `Boolean` | +| `no-try-it` | Disables the "try it" button in the method documentation view. The request editor and the response viewer is still available but you must open it programmatically setting `page` property to ` request` | `Boolean` | +| `manual-navigation` | Disables navigation in the drawer and renders the navigation full screen, when requested. This is ideal to use in the narrow layouts together with `narrow` property. You will have to set the `navigationOpened` property to `true` or `false` to open / close the navigation. | `Boolean` | +| `navigation-opened` | If set and `manual-navigation` attribute is set then it will open / close the full screen navigation. | `Boolean` | + +## Controlling the view + +The `` uses the `path` and `page` properties to control the view. +While `page` is responsible for displaying top level pages (either documentation or try it screen), the `path` property controls which part of the RAML spec is currently displayed (in both of top level screens). + +If required by your use case, you can control the view programmatically. + +The `path` property can be set to display: +- Summary of the API spec +- Documentation included in the spec +- Type +- Resource +- Method + +`path` is simply a JSON path (or x-path) to a specific value of the JavaScript object. + +For example, to display documentation for a method you would set the `path` property to: + +```html + +``` + +Example above will display second method from first resource in the resources tree. You can set attribute `display` to `request` to display a request panel for this method. By default it is set to `docs`. + +Detailed description for building the path can be found in the [raml-path-selector] custom element documentation. + +## Forcing the API Console to send a specific list of headers + +You can force the API Console to send a specific list of headers for each request made by it. To do this set the `append-headers` attribute. It should contain a HTTP headers string. + +If the user declare a header that is declared in the `append-headers` attribute then user value will be overridden. Otherwise headers will be appended to the headers string. + +Use "\n" string to set a new line for the headers string. + +``` + +``` + +[camel case]: https://en.wikipedia.org/wiki/Camel_case +[raml-aware]: https://elements.advancedrestclient.com/elements/raml-aware +[RAML parser]: https://github.com/raml-org/raml-js-parser-2 +[raml-path-selector]: https://elements.advancedrestclient.com/elements/raml-path-selector diff --git a/docs/cors.md b/docs/cors.md new file mode 100644 index 000000000..514c0c0ca --- /dev/null +++ b/docs/cors.md @@ -0,0 +1,228 @@ +# CORS + +There's no easy way to deal with CORS. In the API Console ecosystem there is an extension for Chrome (and soon will be for Firefox) which will proxy the request without CORS limitations. The user (when using selected browsers) will see the install extension banner in the request editor. After installing the +extension all traffic from the console will be redirected to the extension to perform the request (without CORS limitations) and to get the response. + +The console listens for the `api-console-extension-installed` event that is fired by the extension. Once initialized the console will send an event to the extension when the user make the HTTP request. The element responsible for the communication with the extension is [api-console-ext-comm](https://elements.advancedrestclient.com/elements/api-console-ext-comm). + +Other ways to deal with CORS are coming soon. File an issue report in the repo if you can help with this issue. + +# Using proxy server + +One of the ways to deal with CORS is to tell the API console to pass the request through a proxy. +For this you can use `proxy` attribute. Once set then every request made by the console will be passed through the proxy. + +When using proxy, the request URL will be altered before sending it to a transport library (possibly the XHR call) by prefixing the URL with proxy value. + +```html + +``` + +With this configuration a request made to `http://domain.com/path/?query=some+value` endpoint will +become `https://api.proxy.com/api/proxy/http://domain.com/path/?query=some+value`. + +Don't forget to add trailing '/' to the path or produced URL will be invalid. + +If the proxy require to set the URL as a query parameter then `proxy` attribute should end with +parameter name and `=` sign: + +```html + +``` + +In this case be sure to set `proxy-encode-url` attribute which will tell the console to URL encode the URL before appending it to the final URL. + +With this configuration a request made to `http://domain.com/path/?query=some+value` endpoint will +become `https://api.proxy.com/api/proxy/?url=http%3A%2F%2Fdomain.com%2Fpath%2F%3Fquery%3Dsome%2Bvalue`. + +The proxy URL won't be visible by the user and the user can't do anything to change this behavior (until your application doesn't support proxy change in some custom UI). + +# Handling HTTP request by the hosting website / application + +When the user runs the request from the "try it" screen the API Console will fire the `api-console-request` [custom event](https://developer.mozilla.org/en/docs/Web/API/CustomEvent). If your application can handle the transport (by providing a proxy or other solution) you should listen for this event and cancel it by calling `event.preventDefault()`. If the event was cancelled then the API Console will listen for the `api-console-response` custom +event that should contain response details. Otherwise the console will use build in fallback function to get the resource using Fetch API / XHR. + +#### api-console-request custom event + +Event's `detail` object will contain following properties + +Property | Type | Description +----------------|-------------|---------- +`url` | `String` | The request URL. If proxy is set it will be final URL with the proxy value. +`method` | `String` | The HTTP method +`headers` | `String` | HTTP headers string to send with the message +`payload` | `String` | Body to send + +#### api-console-response + +This event must be fired when the hosting app finish the request. It must contain generated Request +and Response object as defined in the [Fetch specification](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch). The API console has a polyfill for the Fetch API already included. + +Property | Type | Description +----------------|-------------|---------- +`request` | `Request` | The request object as defined in the Fetch API spec. See [Request docs](https://developer.mozilla.org/en-US/docs/Web/API/Request) for more details. +`response` | `Response` | The response object as defined in the Fetch API spec. See [Response docs](https://developer.mozilla.org/en-US/docs/Web/API/Response) for more details. +`isXhr` | `Boolean` | Default to `true`. Indicates that the transport method doesn't support advanced timings and redirects information. See [request-panel](https://elements.advancedrestclient.com/elements/raml-request-panel) documentation for detailed description. +`error` | `Error` | When the request / response is errored (`request.ok` equals `false`) then the error object should be set with the human readable message that will be displayed to the user. + +#### Example with handling request / response events + +```javascript +// Start time of executing the request +var startTime; +// Initial request data passed by the event. +var requestData; +/** + * Creates a Headers object based on the HTTP headers string. + * + * @param {String} headers HTTP headers. + * @return {Headers} Parsed headers object. + */ +function createHeaders(headers) { + if (!headers) { + return new Headers(); + } + var result = new Headers(); + var list = headers.split('\n').map(function(line) { + var _parts = line.split(':'); + var _name = _parts[0]; + var _value = _parts[1]; + _name = _name ? _name.trim() : null; + _value = _value ? _value.trim() : null; + if (!_name || !_value) { + return null; + } + return { + name: _name, + value: _value + }; + }).filter(function(item) { + return !!item; + }); + list.forEach(function(item) { + result.append(item.name, item.value); + }); + return result; +} +/** + * Creates a request object from the event's request data. + * + * @param {Object} data Latest request data as in the `api-console-request` object event. + * @return {Request} The Request object. + */ +function createRequest(data) { + var init = { + method: data.method, + mode: 'cors' + }; + if (data.headers) { + init.headers = createHeaders(data.headers); + } + if (['GET', 'HEAD'].indexOf(data.method) !== -1) { + data.payload = undefined; + } else { + if (data.payload) { + init.body = data.payload; + } + } + return new Request(data.url, init); +} +/** + * Creates a response object from the response data. + * If the response is invalid then returned Response object will be errored. + * + * @param {XMLHttpRequest} xhr The XHR object used to make a connection. + * @return {Response} The response object. + */ +function createResponse(xhr) { + var status = xhr.status; + if (!status || status < 200) { + return Response.error(); + } + var init = { + status: status, + statusText: xhr.statusText + }; + var headers = xhr.getAllResponseHeaders(); + if (headers) { + init.headers = createHeaders(headers); + } + try { + return new Response(xhr.responseText, init); + } catch (e) { + return Response.error(); + } +} +// General error handler. +function errorHandler(e) { + var loadTime = performance.now() - startTime; + var request = createRequest(requestData); + var detail = { + request: request, + response: Response.error(), + loadingTime: loadTime, + isXhr: true, + error: new Error('Resource is unavailable') + }; + var event = new CustomEvent('api-console-response', { + cancelable: false, + bubbles: true, + composed: true, + detail: detail + }); + document.body.dispatchEvent(event); +} +// Handler for load event +function loadHandler(e) { + var loadTime = performance.now() - startTime; + var request = createRequest(requestData); + var response = createResponse(e.target); + var detail = { + request: request, + response: response, + loadingTime: loadTime, + isXhr: true + }; + if (!response.ok) { + detail.error = new Error('Resource is unavailable'); + } + var event = new CustomEvent('api-console-response', { + cancelable: false, + bubbles: true, + composed: true, + detail: detail + }); + document.body.dispatchEvent(event); +} +// Handler to the event, sends the request +function consoleRequestHandler(e) { + requestData = e.detail; + var xhr = new XMLHttpRequest(); + xhr.open(requestData.method, requestData.url, true); + if (requestData.headers) { + requestData.headers.split('\n').forEach(function(header) { + var data = header.split(':'); + var name = data[0].trim(); + var value = ''; + if (data[1]) { + value = data[1].trim(); + } + try { + xhr.setRequestHeader(name, value); + } catch (e) { + console.log('Can\'t set header ' + name ' in the XHR call.'); + } + }); + } + xhr.addEventListener('load', loadHandler); + xhr.addEventListener('error', errorHandler); + xhr.addEventListener('timeout', errorHandler); + try { + startTime = performance.now(); + xhr.send(requestData.payload); + } catch (e) { + errorHandler(e); + } +} +window.addEventListener('api-console-request', consoleRequestHandler); +``` diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico deleted file mode 100644 index aad44574c..000000000 Binary files a/docs/images/favicon.ico and /dev/null differ diff --git a/docs/images/manifest/icon-144x144.png b/docs/images/manifest/icon-144x144.png deleted file mode 100644 index 2019b042f..000000000 Binary files a/docs/images/manifest/icon-144x144.png and /dev/null differ diff --git a/docs/images/manifest/icon-192x192.png b/docs/images/manifest/icon-192x192.png deleted file mode 100644 index e2dce915a..000000000 Binary files a/docs/images/manifest/icon-192x192.png and /dev/null differ diff --git a/docs/images/manifest/icon-48x48.png b/docs/images/manifest/icon-48x48.png deleted file mode 100644 index e55c020f7..000000000 Binary files a/docs/images/manifest/icon-48x48.png and /dev/null differ diff --git a/docs/images/manifest/icon-512x512.png b/docs/images/manifest/icon-512x512.png deleted file mode 100644 index b3588b28d..000000000 Binary files a/docs/images/manifest/icon-512x512.png and /dev/null differ diff --git a/docs/images/manifest/icon-72x72.png b/docs/images/manifest/icon-72x72.png deleted file mode 100644 index cb2c0785c..000000000 Binary files a/docs/images/manifest/icon-72x72.png and /dev/null differ diff --git a/docs/images/manifest/icon-96x96.png b/docs/images/manifest/icon-96x96.png deleted file mode 100644 index 16508633d..000000000 Binary files a/docs/images/manifest/icon-96x96.png and /dev/null differ diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index c19f45bd9..000000000 --- a/docs/index.html +++ /dev/null @@ -1,58 +0,0 @@ - - - - - API Console - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/manifest.json b/docs/manifest.json deleted file mode 100644 index c748e7bff..000000000 --- a/docs/manifest.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "name": "API console", - "short_name": "API console", - "start_url": "/?homescreen=1", - "display": "standalone", - "theme_color": "#3f51b5", - "background_color": "#3f51b5", - "icons": [ - { - "src": "images/manifest/icon-192x192.png", - "sizes": "192x192", - "type": "image/png" - }, - { - "src": "images/manifest/icon-512x512.png", - "sizes": "512x512", - "type": "image/png" - } - ] -} diff --git a/docs/method-title-source.png b/docs/method-title-source.png new file mode 100644 index 000000000..99994ab00 Binary files /dev/null and b/docs/method-title-source.png differ diff --git a/docs/method-title.png b/docs/method-title.png new file mode 100644 index 000000000..6c473350f Binary files /dev/null and b/docs/method-title.png differ diff --git a/docs/passing-raml-data.md b/docs/passing-raml-data.md new file mode 100644 index 000000000..15c34ad87 --- /dev/null +++ b/docs/passing-raml-data.md @@ -0,0 +1,129 @@ +# Passing the RAML data + +## Before you begin: asynchronous environment + +Web components are asynchronous by nature. It means that importing the elements, +registering them in the DOM and finally initializing an element is made asynchronously. Therefore you can't expect the element to work right after loading the page (as regular HTML elements does). Consider following example: + +```html + + + +``` + +Running this code on page load will throw a `TypeError` with the message: `parser.loadApi is not a function`. + +It's because at the time of execution of this script block the browser knows nothing about the `raml-js-parser` element. At the time it is an instance of `HTMLUnknownElement`. + +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`. + +To run the code properly you have to listen for the `WebComponentsReady` event. It's fired when the elements are ready to use. + +```html + + + +``` + +## JSON instead of RAML + +The API console web component requires 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 API Console CLI tool). + +Use the [raml-js-parser] element to parse YAML data or to download RAML from remote location. __Note__: You may also use our [raml-js-parser-2] node library as it gives 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 (flattens it's structure so a type doesn't have complex inheritance structure). + +Elements used to build the API Console expects the JSON object to contain complete data about a method / endpoint / type / security scheme and so on. They will not look into nor have access to the data in the root of RAML definition. The enhancer replaces objects into arrays (adding a `key` property to each item) so it can be used in a templating systems. Also `example` property of the RAML is always translated to `examples` array. Finally the enhancer creates `fullUrl` property on each HTTP method so the console don't need to compute it each time you open the documentation page. + +#### Example: parsing and enhancing RAML + +```html + + + +``` + +1) After the elements are initialized (`WebComponentsReady` event) then it calls the `loadApi()` function on the [raml-js-parser] element. +2) The element will fire `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. +3) When the enhancer transform the object it will fire `raml-json-enhance-ready` custom event. The result is in `e.detail.json` property. + +Parsing and enhancing costs a lot depending on RAML structure and number of referenced files. It is a good idea to do it once and cache the results. Then, when the user visit the page again restore cached JSON object and pass it as the `api-console` parameter (see below). + +### Setting RAML data as an HTML attribute + +The basic method to tell the API console what to display is to use the `raml` attribute. It accepts the JavaScript object produced by the parser and the enhancer described above. + +```html + + +``` + +The `` element also have a convenient `json-file` attribute that can be set to point to a file containing the parsed and enhanced JSON data. + +```html + +``` + +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. + +### Using RAML aware to pass the data + +The API console internally uses the [raml-aware] element. +It can be used to pass the RAML data to the console if direct access to the +element is not possible (eg. the console is encapsulated in the [shadow DOM]). + +See the [raml-aware] documentation page for more details. + +#### Example + +```html + + +``` + +```javascript +window.addEventListener('raml-json-enhance-ready', function(e) { + var aware = document.querySelector('raml-aware'); + aware.raml = e.detail.json; +}); +parser.loadApi(urlToApi); +``` + +[build tools]: docs/build-tools.md +[raml-js-enhance]: https://elements.advancedrestclient.com/elements/raml-json-enhance +[raml-js-parser]: https://elements.advancedrestclient.com/elements/raml-js-parser +[raml-js-parser-2]: https://github.com/raml-org/raml-js-parser-2 +[raml-aware]: https://elements.advancedrestclient.com/elements/raml-aware +[shadow DOM]: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM diff --git a/docs/service-worker.js b/docs/service-worker.js deleted file mode 100644 index 909274113..000000000 --- a/docs/service-worker.js +++ /dev/null @@ -1,258 +0,0 @@ -/** - * Copyright 2016 Google Inc. All rights reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -// This generated service worker JavaScript will precache your site's resources. -// The code needs to be saved in a .js file at the top-level of your site, and registered -// from your pages in order to be used. See -// https://github.com/googlechrome/sw-precache/blob/master/demo/app/js/service-worker-registration.js -// for an example of how you can register this script and handle various service worker events. - -/* eslint-env worker, serviceworker */ -/* eslint-disable indent, no-unused-vars, no-multiple-empty-lines, max-nested-callbacks, space-before-function-paren */ -'use strict'; - - - - - -/* eslint-disable quotes, comma-spacing */ -var PrecacheConfig = [["/bower_components/anypoint-styles/anypoint-styles.html","e584adafd34699dd90e18a97c52bd033"],["/bower_components/anypoint-styles/colors.html","417372e96fb8ada00e2ae0e79e955ade"],["/bower_components/anypoint-styles/din-pro.html","f36a651ab9818ec11e2c165e1c66240f"],["/bower_components/anypoint-styles/typography.html","dd38d453fc0fc895756445a2afa4c02c"],["/bower_components/api-console-ext-comm/api-console-ext-comm.html","e72c96a1e2d201e5e0640b93169eb169"],["/bower_components/app-layout/app-drawer-layout/app-drawer-layout.html","a7474857c8dd25d6a9e5aabe763ec01f"],["/bower_components/app-layout/app-drawer/app-drawer.html","6542c3b2545aa1f93c16a6ff04c47c0b"],["/bower_components/app-layout/app-header-layout/app-header-layout.html","0916d57aa30b3c1b54946399c8c01f04"],["/bower_components/app-layout/app-header/app-header.html","f5c92182d2100c582b099fdba4b1267f"],["/bower_components/app-layout/app-scroll-effects/app-scroll-effects-behavior.html","3007817ffcb7fd1cf6528305c0fec9ff"],["/bower_components/app-layout/app-scroll-effects/app-scroll-effects.html","1eaa9e05144414be49e4ee23e16ceca2"],["/bower_components/app-layout/app-scroll-effects/effects/blend-background.html","4723ce7f6429640a812ad866ddddb719"],["/bower_components/app-layout/app-scroll-effects/effects/fade-background.html","3929482c600a21680def557965850501"],["/bower_components/app-layout/app-scroll-effects/effects/material.html","271fe6e745f1a9581a6e01cb3aadce21"],["/bower_components/app-layout/app-scroll-effects/effects/parallax-background.html","391d025dcffee3f042c9d2bdd83be377"],["/bower_components/app-layout/app-scroll-effects/effects/resize-snapped-title.html","4f3bc3dee2d48426998c6e4425df2b14"],["/bower_components/app-layout/app-scroll-effects/effects/resize-title.html","a78d5b787591fb1728631fc5e087cd1c"],["/bower_components/app-layout/app-scroll-effects/effects/waterfall.html","6cbd757de769cd5af213aaebb8780745"],["/bower_components/app-layout/app-toolbar/app-toolbar.html","bde0a79d3265bef565ee86c699b6bbae"],["/bower_components/app-layout/helpers/helpers.html","95b52c0c05f77b65bc1b5dc0715d2495"],["/bower_components/app-route/app-location.html","0c082f44abb664591f5b99e57a3855e6"],["/bower_components/app-route/app-route-converter-behavior.html","3b85a02b434cbccdcb87396be3554258"],["/bower_components/app-route/app-route.html","ee6897a01647904badcc856c1a4cb6ec"],["/bower_components/arc-definitions/arc-definitions.html","85824e3d3444bdf673a9dd18e9dea943"],["/bower_components/arc-icons/arc-icons.html","909ae34db90b5b240ce5d33c5851f140"],["/bower_components/auth-methods/auth-method-basic.html","f9d65fe800aa8f05930de749f1a08b9c"],["/bower_components/auth-methods/auth-method-digest.html","d63debb2c7a0b398652eb3099ed88ed7"],["/bower_components/auth-methods/auth-method-ntlm.html","493088b3effd5bf5332646a19fa93fda"],["/bower_components/auth-methods/auth-method-oauth1.html","bf3c8b835bccc5c669e86541342b6cf4"],["/bower_components/auth-methods/auth-method-oauth2.html","7e7115cb8ed927dec50631ef733c2c25"],["/bower_components/auth-methods/auth-methods-behavior.html","f75e3558e605a6d9819be3b415f3ef90"],["/bower_components/auth-methods/auth-methods-styles.html","8a4efe8653650ed50a0787063d129303"],["/bower_components/auth-methods/auth-methods.html","7e76a0b0f60bed3615d240cf44b54094"],["/bower_components/auth-methods/cryptojs-import.html","120f21756fd337b0673bd6f7a9354721"],["/bower_components/auth-methods/polyfills.html","af39ddac2975932f58bd01d46f11fbf4"],["/bower_components/authorization-panel/authorization-panel.html","d4291af6d81e1bcc5355b6ac94e7d789"],["/bower_components/body-form-editor/body-form-editor.html","d8583f95eade6ebdbc9033d666985e91"],["/bower_components/body-json-editor/body-json-editor-behavior.html","ee8ed352062e91e0250d37496373adba"],["/bower_components/body-json-editor/body-json-editor.html","867426bb4cfec41f3616a2d98a8ac67c"],["/bower_components/body-json-editor/object-editor.html","d42a3b38f422a9fb0f528f96f29f22d4"],["/bower_components/body-json-editor/simple-type-editor.html","11f64899f101276ba54ed8b113680906"],["/bower_components/clipboard-copy/clipboard-copy.html","b272640d50d335d1c7222f3c460fd13a"],["/bower_components/code-mirror/code-mirror.html","da078f93749d810171b8287af6d6e12f"],["/bower_components/code-mirror/code-mirror.js","ccb3a8562e8dde311eb3e3555792279b"],["/bower_components/code-mirror/codemirror-import.html","0e7d9ef014c4c4819796bba68ab02c25"],["/bower_components/code-mirror/styles/3024-day-styles.html","b985602d6542776da82383fc47cb0e3b"],["/bower_components/code-mirror/styles/3024-night-styles.html","54c40cfd0f460f9c419792c2631525b2"],["/bower_components/code-mirror/styles/ambiance-mobile-styles.html","c9e4ad1a081fd86fcd84787f1a5f5083"],["/bower_components/code-mirror/styles/ambiance-styles.html","ac0285940410e79eb624b5beae9b2f7d"],["/bower_components/code-mirror/styles/base16-dark-styles.html","3163a372020325448d5d8c04ad3f23a0"],["/bower_components/code-mirror/styles/base16-light-styles.html","5b0a82fa682635cc5a580c7a0ff31fbe"],["/bower_components/code-mirror/styles/blackboard-styles.html","0465045a6de537268708da2dbdfa6bc0"],["/bower_components/code-mirror/styles/cobalt-styles.html","5fc838f30c9a1f6ce193fe36481eb12a"],["/bower_components/code-mirror/styles/codemirror-styles.html","cfa034b22b137ba0020357f87f8fd754"],["/bower_components/code-mirror/styles/colorforth-styles.html","36078c64a6940ec64a3ee6512feaaf4e"],["/bower_components/code-mirror/styles/eclipse-styles.html","0795336fe2b87cc17d662a89c4cebc85"],["/bower_components/code-mirror/styles/elegant-styles.html","0dd97d55061a5cfb109fd42796468842"],["/bower_components/code-mirror/styles/erlang-dark-styles.html","cc27845618f95c7fc0a7c4abc53fa530"],["/bower_components/code-mirror/styles/lesser-dark-styles.html","c32d46b2a0dff46054490885ebf98ef1"],["/bower_components/code-mirror/styles/liquibyte-styles.html","38524b3e9bf598d35b5d1fb195dbb926"],["/bower_components/code-mirror/styles/mbo-styles.html","5d332cdb1621a7276a0d85d230f3270d"],["/bower_components/code-mirror/styles/mdn-like-styles.html","98b778556ede0013f12fea6f2ba6663a"],["/bower_components/code-mirror/styles/midnight-styles.html","441dca2632dc775efa80642fad6254a5"],["/bower_components/code-mirror/styles/monokai-styles.html","81446baf66034eec7e57cfbd10518394"],["/bower_components/code-mirror/styles/neat-styles.html","ec6d8846a03ded43b4a9583a5e762307"],["/bower_components/code-mirror/styles/neo-styles.html","a7df507bbf5f33cb33d3b369dcc85b43"],["/bower_components/code-mirror/styles/night-styles.html","dd48f25d2153614d8f537f335cb99e31"],["/bower_components/code-mirror/styles/paraiso-dark-styles.html","6bf2c1d10fe71335b68fc7ddd4923cf8"],["/bower_components/code-mirror/styles/paraiso-light-styles.html","27ead6746fa8e17d025bc892514fbd9d"],["/bower_components/code-mirror/styles/pastel-on-dark-styles.html","f1745773022efd8e3ed6d6248f7905dd"],["/bower_components/code-mirror/styles/rubyblue-styles.html","1c692750217822b058a1f0417d780eac"],["/bower_components/code-mirror/styles/solarized-styles.html","e3beecdbecc9a6ef1dae06f4c66b34f4"],["/bower_components/code-mirror/styles/the-matrix-styles.html","73cf2bb2d0689ec25bac3b1dcec33b65"],["/bower_components/code-mirror/styles/tomorrow-night-bright-styles.html","febb8bd0a1c87e422b4373d36749c9ad"],["/bower_components/code-mirror/styles/tomorrow-night-eighties-styles.html","fc458d98bc0ba272c88883db41a28b10"],["/bower_components/code-mirror/styles/ttcn-styles.html","f6adc6f42be6409c4f5c965ba5db18db"],["/bower_components/code-mirror/styles/twilight-styles.html","d305a5dd01cf993f4fa1db692b7e6615"],["/bower_components/code-mirror/styles/vibrant-ink-styles.html","ff519a531122d165370bb99f8412f61e"],["/bower_components/code-mirror/styles/xq-dark-styles.html","e169f6ba0d10d62efbe11070f762b62f"],["/bower_components/code-mirror/styles/xq-light-styles.html","513c763cc063597b763ebafea1dde418"],["/bower_components/code-mirror/styles/zenburn-styles.html","304b8edc874f891ecfcb99b653eec711"],["/bower_components/codemirror/addon/mode/loadmode.js","6eb4ac9f24c5a2d7319515988cb655b4"],["/bower_components/codemirror/lib/codemirror.js","2719da3d45f02b4cdeacef328d259d0a"],["/bower_components/codemirror/mode/htmlmixed/htmlmixed.js","c953202cc23df9fa37e9ed48901d5fe1"],["/bower_components/codemirror/mode/meta.js","c8c6ab0328956aaa5b3fa1920b7062ef"],["/bower_components/cryptojslib/rollups/md5.js","82cad5af7bcd413ae7e9e4900ab18b68"],["/bower_components/date-time/date-time.html","08063718941db19a695682aa64171b38"],["/bower_components/docs-parameters-table/docs-body-parameters-table.html","4093320677e9e0a69530aa8e499cb361"],["/bower_components/docs-parameters-table/docs-body-table.html","293e44ef8bda26c79447f4436c5be5af"],["/bower_components/docs-parameters-table/docs-form-parameters-table.html","f864bcca6d72e244451bd50daf19ecda"],["/bower_components/docs-parameters-table/docs-headers-table.html","2a90dddad70742bb963098b7ffbccb2b"],["/bower_components/docs-parameters-table/docs-json-parameters-table.html","55fb57b483697a6f0d3bbcf6d6921cf4"],["/bower_components/docs-parameters-table/docs-parameters-behavior.html","890e05ff09ceaa8a964030cbc53e8593"],["/bower_components/docs-parameters-table/docs-parameters-table-shared-styles.html","f0bdd80fa3eca0007384742c003bfd45"],["/bower_components/docs-parameters-table/docs-parameters-table.html","112f2d1e9e5f27fd9fbc596d569efcd2"],["/bower_components/docs-parameters-table/docs-xml-parameters-table.html","7b32448a089b61d8e73b28027b37f56b"],["/bower_components/docs-parameters-table/structure-display.html","c6c27b70051c6d7cc35582acfb86e432"],["/bower_components/error-message/error-message.html","02690aa161f9f6ae62ecb458b9a694c8"],["/bower_components/fetch-polyfill/fetch-polyfill.html","f3dd60ab9794368730ed2a4bdc2bbadd"],["/bower_components/fetch/fetch.js","f12fc754bbd66a3d50c516237e8dda52"],["/bower_components/font-roboto/roboto.html","09500fd5adfad056ff5aa05e2aae0ec5"],["/bower_components/headers-list-view/headers-list-item-value.html","662173348d541275bebb7378393d39ab"],["/bower_components/headers-list-view/headers-list-item.html","d30dc018509653937a0a533dd2e4d386"],["/bower_components/headers-list-view/headers-list-view.html","6dcc383027b2262ea0e98944919efaea"],["/bower_components/headers-parser-behavior/headers-parser-behavior.html","0d327417b4a9e4b0f839f7b880c81cfb"],["/bower_components/iron-a11y-announcer/iron-a11y-announcer.html","a3bd031e39dde38cb8e619f670ee50f7"],["/bower_components/iron-a11y-keys-behavior/iron-a11y-keys-behavior.html","c4c3d44402c9d456c38c14da04d206b9"],["/bower_components/iron-a11y-keys/iron-a11y-keys.html","fd2760ee5676b7615aaa24d695c5295d"],["/bower_components/iron-ajax/iron-ajax.html","d606b330d7bd040660a53a5cda7f8acf"],["/bower_components/iron-ajax/iron-request.html","c2d289c4b20653353cff315cf247a45e"],["/bower_components/iron-behaviors/iron-button-state.html","6565a80d1af09299c1201f8286849c3b"],["/bower_components/iron-behaviors/iron-control-state.html","1c12ee539b1dbbd0957ae26b3549cc13"],["/bower_components/iron-checked-element-behavior/iron-checked-element-behavior.html","6fd1055c2c04382401dc910a0db569c6"],["/bower_components/iron-collapse/iron-collapse.html","30ca05c987397312c698967a9bbe6499"],["/bower_components/iron-dropdown/iron-dropdown-scroll-manager.html","fe09653502aaa6271d6ba8533de60f22"],["/bower_components/iron-dropdown/iron-dropdown.html","0c8c3226b6e6a351b098fa4d794ee702"],["/bower_components/iron-fit-behavior/iron-fit-behavior.html","884c6983ce660f254b47b5d69819f44d"],["/bower_components/iron-flex-layout/classes/iron-flex-layout.html","52518a396b7b6638323e33320af1e2a5"],["/bower_components/iron-flex-layout/classes/iron-shadow-flex-layout.html","82233435af1c9e0c4f7533a5db91d30f"],["/bower_components/iron-flex-layout/iron-flex-layout.html","be17bfc442cd8270b7dec1bb39051621"],["/bower_components/iron-form-element-behavior/iron-form-element-behavior.html","a64177311979fc6a6aae454cb85ea2be"],["/bower_components/iron-form/iron-form.html","d567cf610fac57ae3c30af80c5400750"],["/bower_components/iron-icon/iron-icon.html","f2a0dfd0b79864b4f4efb578417a3fef"],["/bower_components/iron-iconset-svg/iron-iconset-svg.html","8d0d7213b8c3325ca7e5a658ca9aaf17"],["/bower_components/iron-input/iron-input.html","3e393eda6c241be2817ce0acc512bcf6"],["/bower_components/iron-location/iron-location.html","0ca9fd93d23992a9340ce7c433557226"],["/bower_components/iron-location/iron-query-params.html","32a96be5536aea89a925d16146cb7015"],["/bower_components/iron-media-query/iron-media-query.html","7436f9608ebd2d31e4b346921651f84b"],["/bower_components/iron-menu-behavior/iron-menu-behavior.html","2b9d30d90893eba83cb702c70b6e6b29"],["/bower_components/iron-menu-behavior/iron-menubar-behavior.html","a0cc6674fc6d9d7ba0b68ff680b4e56b"],["/bower_components/iron-meta/iron-meta.html","dd4ef14e09c5771e70292d70963f6718"],["/bower_components/iron-overlay-behavior/iron-focusables-helper.html","1607d4d8a7d922ade7894167368ccc31"],["/bower_components/iron-overlay-behavior/iron-overlay-backdrop.html","35013b4b97041ed6b63cf95dbb9fbcb4"],["/bower_components/iron-overlay-behavior/iron-overlay-behavior.html","9e9090df0515a2c8b755bd9c2e944b45"],["/bower_components/iron-overlay-behavior/iron-overlay-manager.html","707308044cec15e2d3c85cd28d152e89"],["/bower_components/iron-pages/iron-pages.html","5872a2ad58225c94b14ddea747f67cbd"],["/bower_components/iron-range-behavior/iron-range-behavior.html","34f5b83882b6b6c5cfad7543caab080e"],["/bower_components/iron-resizable-behavior/iron-resizable-behavior.html","e93449ccd4312e4e30060c87bd52ed25"],["/bower_components/iron-scroll-target-behavior/iron-scroll-target-behavior.html","d0eb39331820f58f3cdcebaa0eed0209"],["/bower_components/iron-selector/iron-multi-selectable.html","46d6620acd7bad986d81097d9ca91692"],["/bower_components/iron-selector/iron-selectable.html","65b04f3f5f1b551d91a82b36f916f6b6"],["/bower_components/iron-selector/iron-selection.html","83545b7d1eae4020594969e6b9790b65"],["/bower_components/iron-selector/iron-selector.html","4d2657550768bec0788eba5190cddc66"],["/bower_components/iron-validatable-behavior/iron-validatable-behavior.html","02bf0434cc1a0d09e18413dea91dcea1"],["/bower_components/json-table/json-table-array.html","9f17fce71e64ff1a4a201827c821f42b"],["/bower_components/json-table/json-table-behavior.html","9b4cfc95ec45649826f1a9c5b1f23b15"],["/bower_components/json-table/json-table-object.html","3d04695608c1f0feccc2c389cfa495f4"],["/bower_components/json-table/json-table-primitive-teaser.html","5882d34e1717f8f6b3898a3a07347ee1"],["/bower_components/json-table/json-table.html","6cca79a83878c0e7c74cad9137f60f4c"],["/bower_components/json-viewer/js-max-number-error.html","03af0efc44ef657c3c540e66233aef08"],["/bower_components/json-viewer/json-viewer.html","88f2b29db61fd169e1e7b0de7648af29"],["/bower_components/markdown-styles/markdown-styles.html","3f4d6dc74105b92d57c25e4cb310c4a1"],["/bower_components/marked-element/marked-element.html","05fe17af531201607a52fcecb1e4b928"],["/bower_components/marked-element/marked-import.html","935603373e4046660d3944abb73939f1"],["/bower_components/marked/lib/marked.js","eb770edf3f9eec6adb25b8fe65e15312"],["/bower_components/neon-animation/animations/fade-in-animation.html","b814c818dbcffe2bb50563e1406497df"],["/bower_components/neon-animation/animations/fade-out-animation.html","44988226230af0e6d92f0988fc8688e2"],["/bower_components/neon-animation/animations/opaque-animation.html","8e2f63bbc648796f3ed96834a5553d07"],["/bower_components/neon-animation/neon-animatable-behavior.html","270f52231303cae4cb8e3fadb5a805c1"],["/bower_components/neon-animation/neon-animation-behavior.html","eb1cdd9cd9d780a811fd25e882ba1f8e"],["/bower_components/neon-animation/neon-animation-runner-behavior.html","782cac67e6cb5661d36fb32d9129ff03"],["/bower_components/neon-animation/web-animations.html","b310811179297697d51eac3659df7776"],["/bower_components/oauth-authorization/oauth2-authorization.html","b068779e99b87e8152b777a3168af298"],["/bower_components/oauth2-scope-selector/oauth2-scope-selector.html","fda6091c4948b7195dee2fe05126f25a"],["/bower_components/paper-autocomplete/paper-autocomplete.html","af19486b6a357c4b47c5587b4274d5ea"],["/bower_components/paper-behaviors/paper-button-behavior.html","edddd3f97cf3ea944f3a48b4154939e8"],["/bower_components/paper-behaviors/paper-checked-element-behavior.html","59702db25efd385b161ad862b8027819"],["/bower_components/paper-behaviors/paper-inky-focus-behavior.html","51a1c5ccd2aae4c1a0258680dcb3e1ea"],["/bower_components/paper-behaviors/paper-ripple-behavior.html","b6ee8dd59ffb46ca57e81311abd2eca0"],["/bower_components/paper-button/paper-button.html","3f061a077ee938fac479622156071296"],["/bower_components/paper-checkbox/paper-checkbox.html","1c5af2743fed525fe96db75f8a12b2d2"],["/bower_components/paper-dialog-behavior/paper-dialog-behavior.html","b9cf5384b29cd12a724965080916b6f1"],["/bower_components/paper-dialog-behavior/paper-dialog-shared-styles.html","8fb5282b6149bc429b6baef5c077a285"],["/bower_components/paper-dialog-scrollable/paper-dialog-scrollable.html","49e3023a68129496c360dc9613f34bfc"],["/bower_components/paper-dialog/paper-dialog.html","7a8d86ed89c215baf8cc42e4d7335271"],["/bower_components/paper-dropdown-menu/paper-dropdown-menu-icons.html","d309383cfdcf6733d4e6827c3b877c72"],["/bower_components/paper-dropdown-menu/paper-dropdown-menu-shared-styles.html","c18c68e91e13e2102f577c1c55ce7598"],["/bower_components/paper-dropdown-menu/paper-dropdown-menu.html","879115bf8199d7d13c336144a32115d4"],["/bower_components/paper-icon-button/paper-icon-button.html","2a75de00f858ae1e894ab21344464787"],["/bower_components/paper-input/paper-input-addon-behavior.html","de7b482dc1fb01847efba9016db16206"],["/bower_components/paper-input/paper-input-behavior.html","3960579058d3ba0a74ae7b67b78f53c2"],["/bower_components/paper-input/paper-input-char-counter.html","94c2003f281325951e3bf5b927a326bb"],["/bower_components/paper-input/paper-input-container.html","0ddbde66d15452d5bdec103ef876e5af"],["/bower_components/paper-input/paper-input-error.html","b90f3a86d797f1bdbbb4d158aeae06ab"],["/bower_components/paper-input/paper-input.html","3385511052db3467ca6ec155faa619ad"],["/bower_components/paper-item/paper-item-behavior.html","82636a7562fd8b0be5b15646ee461588"],["/bower_components/paper-item/paper-item-body.html","8b91d21da1ac0ab23442d05b4e377286"],["/bower_components/paper-item/paper-item-shared-styles.html","31466267014182098267f1b9303f656e"],["/bower_components/paper-item/paper-item.html","e614731572c425b144aa8a9da24ee3ea"],["/bower_components/paper-listbox/paper-listbox.html","bfbc631d72b3e7b2b611c9a32430e3c6"],["/bower_components/paper-masked-input/paper-masked-input.html","69e41875e2381a25161ea1e16fcc71f7"],["/bower_components/paper-masked-input/paper-masked-input.js","e101fa7eb6476003d7e57fa7f324c341"],["/bower_components/paper-material/paper-material-shared-styles.html","d0eeeb696e55702f3a38ef1ad0058f59"],["/bower_components/paper-material/paper-material.html","47301784c93c3d9989abfbab68ec9859"],["/bower_components/paper-menu-button/paper-menu-button-animations.html","a6d6ed67a145ca00d4487c40c4b06273"],["/bower_components/paper-menu-button/paper-menu-button.html","2b2f79e8b3b50e4aabd2dd3ada9b6814"],["/bower_components/paper-menu/paper-menu-shared-styles.html","9b2ae6e8b26011a37194ea3b4bdd043d"],["/bower_components/paper-menu/paper-menu.html","5270d7b4b603d9fdfcfdb079c750a3cd"],["/bower_components/paper-progress/paper-progress.html","5dd0b9f89efdfd4f3cce0a13bd67fe6f"],["/bower_components/paper-ripple/paper-ripple.html","e22bc21b61184cb28125d16f9d80fb59"],["/bower_components/paper-spinner/paper-spinner-behavior.html","82e814c4460e8803f6f57cc457658adf"],["/bower_components/paper-spinner/paper-spinner-styles.html","a2122d2c0f3ac98e6911160d8886d31a"],["/bower_components/paper-spinner/paper-spinner.html","940e64bbde54dad918d0f5c0e247a8bd"],["/bower_components/paper-styles/color.html","430305db311431da78c0a6e1236f9ebe"],["/bower_components/paper-styles/default-theme.html","c910188e898624eb890898418de20ee0"],["/bower_components/paper-styles/paper-styles.html","3fd71f69f3adc823ef9c03611d296cfc"],["/bower_components/paper-styles/shadow.html","fc449492f51292636b499bc5d7b9b036"],["/bower_components/paper-styles/typography.html","bdd7f31bb85f116ce97061c4135b74c9"],["/bower_components/paper-tabs/paper-tab.html","395fdc6be051eb7218b1c77a94eff726"],["/bower_components/paper-tabs/paper-tabs-icons.html","9fb57777c667562392afe684d85ddbe2"],["/bower_components/paper-tabs/paper-tabs.html","b2a17f55f79d24c9c4046ffd361636b9"],["/bower_components/paper-toast/paper-toast.html","f64d10724104f3751cae8b764aef56ff"],["/bower_components/paper-tooltip/paper-tooltip.html","ba34997662a16417bf99bac94287a986"],["/bower_components/payload-parser-behavior/payload-parser-behavior.html","e6fbbddd252f39db34911c711cea2f3b"],["/bower_components/polymer/polymer-micro.html","54ff0b440c8f9e346afd3bea5c340120"],["/bower_components/polymer/polymer-mini.html","99da171cb18148c2147ea8dd0a6dbc5a"],["/bower_components/polymer/polymer.html","74553dc61f5b3f5138d044de0fea721c"],["/bower_components/prism-element/prism-highlighter.html","d46d0ba17ad96d2732d9bff0d7139c5b"],["/bower_components/prism-element/prism-import.html","94e49629fc3c5cb76c1e23563547923f"],["/bower_components/prism-element/prism-theme-default.html","440043a3ffdbed9376cfe428c9af6051"],["/bower_components/prism-highlight/prism-highlight.html","2473370124dc7b95e5c1a1902486738a"],["/bower_components/prism-highlight/prism-import.html","604de06cd9176959e921f1f41020843f"],["/bower_components/prism-highlight/prism-styles.html","e5dc3c82be7fdbd1fa46d98e3bcd8349"],["/bower_components/prism/prism.js","69667d54be5bff2bf94190b92fcd3ba2"],["/bower_components/prism/themes/prism.css","298e3aafa62f48b863042aa3696a2b34"],["/bower_components/promise-polyfill/Promise-Statics.js","a4fbefd3bdb3ab76e6e7f788a902f7ba"],["/bower_components/promise-polyfill/Promise.js","5afb14fd81497aca81bf25929d65b02d"],["/bower_components/promise-polyfill/promise-polyfill-lite.html","06470312beff013fc54695e0bdda2cb3"],["/bower_components/promise-polyfill/promise-polyfill.html","97dd009429dbc654aa105abcd0dfb927"],["/bower_components/raml-aware/raml-aware.html","309278b97c154fe7b382dbb01d400a9a"],["/bower_components/raml-behaviors/raml-behavior.html","d70bd8bd1aee37305ee718391dda74c5"],["/bower_components/raml-body-editor-panel/cm-arc-styles.html","19cd40f0d398492ba71c8e3faea572ae"],["/bower_components/raml-body-editor-panel/raml-body-editor-panel.html","b405ef686553bf7028ad5c0894994699"],["/bower_components/raml-docs-documentation-viewer/raml-docs-documentation-viewer.html","b49c03c28d15d3b203291fd1115f45fc"],["/bower_components/raml-docs-method-viewer/raml-docs-method-viewer.html","4803091eb4098ba4c2e42d5afdaecdd0"],["/bower_components/raml-docs-resource-viewer/raml-docs-resource-viewer.html","812dae09934ba7a56bf3a2670a3b6c9e"],["/bower_components/raml-docs-response-panel/raml-docs-response-panel.html","da8122ca0db37016a28f9883094282ff"],["/bower_components/raml-docs-types-viewer/raml-docs-types-viewer.html","f395ab550b39b1241cd29213ba21be39"],["/bower_components/raml-documentation-panel/raml-documentation-empty-state.html","57bea3af158d9b72b980f3a5cdcabc03"],["/bower_components/raml-documentation-panel/raml-documentation-panel-icons.html","1cfb130a67737335f06797fad9bd3aba"],["/bower_components/raml-documentation-panel/raml-documentation-panel.html","330d706ac1bb121556b6fb041c65d621"],["/bower_components/raml-headers-form/raml-headers-form.html","010beb48c3c642f9ebe9e8d09ce6a95d"],["/bower_components/raml-js-parser/polyfills.js","f9fdcb65e10594093dae53a48537cf2d"],["/bower_components/raml-js-parser/raml-1-parser.js","8c02901886b316eb6bad4928b9114e2d"],["/bower_components/raml-js-parser/raml-js-parser-imports.html","ad016d6bc511d952554f680f6b1b675a"],["/bower_components/raml-js-parser/raml-js-parser.html","51df81a49549e02f2a4aa69b14cb8336"],["/bower_components/raml-json-enhance/raml-json-enhance.html","7a2ae8fdf04cad4091448a6f80466679"],["/bower_components/raml-path-selector/path-selector-behavior.html","9f3f81e07c171569abab573f882f9996"],["/bower_components/raml-path-selector/path-selector-documentation.html","249a9767db8c2030c9c0591b198728f8"],["/bower_components/raml-path-selector/path-selector-resource.html","86a18a6dcf442b6149f1c6a82144fdb3"],["/bower_components/raml-path-selector/path-selector-styles.html","8a087f62c519918d21d1aa641d214b67"],["/bower_components/raml-path-selector/path-selector-types.html","31601f2ff27577fc72672a5ab9b519de"],["/bower_components/raml-path-selector/raml-documentation-tree-item.html","9a8a37fa112d16aeeb62ee12001b184b"],["/bower_components/raml-path-selector/raml-path-selector.html","1ca51cc11b52f0cad4a3c8922371b063"],["/bower_components/raml-path-selector/raml-resource-tree-item.html","700f8724d4ae01ae06515e902f30ce57"],["/bower_components/raml-path-selector/raml-structure-tree.html","2a26a282cd028939470b37a81457612e"],["/bower_components/raml-path-selector/raml-tree-item-behavior.html","02e14e400529ae35aa6623ffaaa8ab00"],["/bower_components/raml-path-selector/raml-tree-item-styles.html","ff44b7485e729218b79362e63b3d3fbd"],["/bower_components/raml-path-selector/raml-type-tree-item.html","f2a3a5d140b0e63e90f78bfeb7ddbbce"],["/bower_components/raml-path-to-object/raml-path-to-object.html","a18e13278b68ee6287b8b9417ca14d88"],["/bower_components/raml-request-headers-editor/cm-arc-styles.html","669bb1afe360e5e6454e929a34a2374f"],["/bower_components/raml-request-headers-editor/cm-headers-addon.js","88fbfaecc1a2b5d6e34088aae5feac52"],["/bower_components/raml-request-headers-editor/cm-hint-http-headers.js","5c24d9c0cb263e210e72f3963d19f8c5"],["/bower_components/raml-request-headers-editor/cm-modules-import.html","5c5c379db357d0296e5103387a8aaec7"],["/bower_components/raml-request-headers-editor/cm-show-hint.js","e0edcfbc041c4afc31acf0391e9820cb"],["/bower_components/raml-request-headers-editor/raml-request-headers-editor.html","f60cf35454e31cc9d52431333bdd58b6"],["/bower_components/raml-request-panel/raml-request-panel-simple-xhr.html","854cb79964d2459817f811bdef5a2dd8"],["/bower_components/raml-request-panel/raml-request-panel.html","082116a2323e5f7689f21ff97b92dab0"],["/bower_components/raml-request-parameters-editor/raml-request-parameters-editor.html","47a14708228e685b9ac83cf6f8f192ea"],["/bower_components/raml-request-parameters-editor/raml-request-parameters-form.html","10cd0c1456a61fa6778aa6dd52d8116e"],["/bower_components/raml-request-url-editor/raml-request-url-editor.html","8d881518a8027d62235fdb63ada13c93"],["/bower_components/raml-request-url-editor/url-input.html","9ce9dbf508b062dcf894a8c3174403e4"],["/bower_components/raml-summary-view/raml-summary-view.html","09672f33184f0cbe0a3565474a8099d9"],["/bower_components/request-timings/request-timings-panel.html","ee2e15575cbe7fcf069738e7e026ef2d"],["/bower_components/request-timings/request-timings.html","54ced6545da5137ad456c255add61902"],["/bower_components/response-body-view/response-body-view.html","e1cdd0aab1afc2853b5192c98df44b95"],["/bower_components/response-error-view/response-error-view.html","e26ef786553132e090070153866d49f7"],["/bower_components/response-highlighter/response-highlighter.html","c478fea775adef81e02a91fc6fc51923"],["/bower_components/response-raw-viewer/response-raw-viewer.html","c300e4d57747c8c65b56c98db80284ac"],["/bower_components/response-status-view/http-source-message-view.html","8c15bc45fd062c5345af48d4c6b6a2d8"],["/bower_components/response-status-view/response-status-view.html","9464e03732d1b674ef9c4cd25c481d75"],["/bower_components/response-status-view/status-message.html","021cdf1241bb037c1ae11c28ef8306f1"],["/bower_components/response-view/response-view.html","cb9e7d219f015b98d83197ee9864c8e5"],["/bower_components/text-search-behavior/text-search-behavior.html","0f6f3b6399e8f62ff6db80d8947a0466"],["/bower_components/web-animations-js/web-animations-next-lite.min.js","04197e2ccec914fa460eef2ac140c853"],["/bower_components/webcomponentsjs/webcomponents-lite.min.js","02395895d5d08242c6ba93518a6da2c5"],["/bower_components/xml-viewer/xml-viewer.html","9171cd035e535e2688ebea45f0cc93e4"],["/index.html","88129d9985f6b7b463e353e4b4234bc6"],["/manifest.json","5120ac22c707f311d088b94ba5ca80ed"],["/src/api-console-app.html","fde2fb8b9177097dab139a65b8a65801"],["/src/api-console-styles.html","39101a38ee658702aa1a1968c8642822"],["/src/docs.html","267de9abee58321407bbc4116a77c0b8"],["/src/request.html","6f486882acdd9db30076af45e0fe3b63"],["/src/view404.html","6fdb77e7c1f4f6936b55127292007876"]]; -/* eslint-enable quotes, comma-spacing */ -var CacheNamePrefix = 'sw-precache-v1--' + (self.registration ? self.registration.scope : '') + '-'; - - -var IgnoreUrlParametersMatching = [/^utm_/]; - - - -var addDirectoryIndex = function (originalUrl, index) { - var url = new URL(originalUrl); - if (url.pathname.slice(-1) === '/') { - url.pathname += index; - } - return url.toString(); - }; - -var getCacheBustedUrl = function (url, param) { - param = param || Date.now(); - - var urlWithCacheBusting = new URL(url); - urlWithCacheBusting.search += (urlWithCacheBusting.search ? '&' : '') + - 'sw-precache=' + param; - - return urlWithCacheBusting.toString(); - }; - -var isPathWhitelisted = function (whitelist, absoluteUrlString) { - // If the whitelist is empty, then consider all URLs to be whitelisted. - if (whitelist.length === 0) { - return true; - } - - // Otherwise compare each path regex to the path of the URL passed in. - var path = (new URL(absoluteUrlString)).pathname; - return whitelist.some(function(whitelistedPathRegex) { - return path.match(whitelistedPathRegex); - }); - }; - -var populateCurrentCacheNames = function (precacheConfig, - cacheNamePrefix, baseUrl) { - var absoluteUrlToCacheName = {}; - var currentCacheNamesToAbsoluteUrl = {}; - - precacheConfig.forEach(function(cacheOption) { - var absoluteUrl = new URL(cacheOption[0], baseUrl).toString(); - var cacheName = cacheNamePrefix + absoluteUrl + '-' + cacheOption[1]; - currentCacheNamesToAbsoluteUrl[cacheName] = absoluteUrl; - absoluteUrlToCacheName[absoluteUrl] = cacheName; - }); - - return { - absoluteUrlToCacheName: absoluteUrlToCacheName, - currentCacheNamesToAbsoluteUrl: currentCacheNamesToAbsoluteUrl - }; - }; - -var stripIgnoredUrlParameters = function (originalUrl, - ignoreUrlParametersMatching) { - var url = new URL(originalUrl); - - url.search = url.search.slice(1) // Exclude initial '?' - .split('&') // Split into an array of 'key=value' strings - .map(function(kv) { - return kv.split('='); // Split each 'key=value' string into a [key, value] array - }) - .filter(function(kv) { - return ignoreUrlParametersMatching.every(function(ignoredRegex) { - return !ignoredRegex.test(kv[0]); // Return true iff the key doesn't match any of the regexes. - }); - }) - .map(function(kv) { - return kv.join('='); // Join each [key, value] array into a 'key=value' string - }) - .join('&'); // Join the array of 'key=value' strings into a string with '&' in between each - - return url.toString(); - }; - - -var mappings = populateCurrentCacheNames(PrecacheConfig, CacheNamePrefix, self.location); -var AbsoluteUrlToCacheName = mappings.absoluteUrlToCacheName; -var CurrentCacheNamesToAbsoluteUrl = mappings.currentCacheNamesToAbsoluteUrl; - -function deleteAllCaches() { - return caches.keys().then(function(cacheNames) { - return Promise.all( - cacheNames.map(function(cacheName) { - return caches.delete(cacheName); - }) - ); - }); -} - -self.addEventListener('install', function(event) { - event.waitUntil( - // Take a look at each of the cache names we expect for this version. - Promise.all(Object.keys(CurrentCacheNamesToAbsoluteUrl).map(function(cacheName) { - return caches.open(cacheName).then(function(cache) { - // Get a list of all the entries in the specific named cache. - // For caches that are already populated for a given version of a - // resource, there should be 1 entry. - return cache.keys().then(function(keys) { - // If there are 0 entries, either because this is a brand new version - // of a resource or because the install step was interrupted the - // last time it ran, then we need to populate the cache. - if (keys.length === 0) { - // Use the last bit of the cache name, which contains the hash, - // as the cache-busting parameter. - // See https://github.com/GoogleChrome/sw-precache/issues/100 - var cacheBustParam = cacheName.split('-').pop(); - var urlWithCacheBusting = getCacheBustedUrl( - CurrentCacheNamesToAbsoluteUrl[cacheName], cacheBustParam); - - var request = new Request(urlWithCacheBusting, - {credentials: 'same-origin'}); - return fetch(request).then(function(response) { - if (response.ok) { - return cache.put(CurrentCacheNamesToAbsoluteUrl[cacheName], - response); - } - - console.error('Request for %s returned a response status %d, ' + - 'so not attempting to cache it.', - urlWithCacheBusting, response.status); - // Get rid of the empty cache if we can't add a successful response to it. - return caches.delete(cacheName); - }); - } - }); - }); - })).then(function() { - return caches.keys().then(function(allCacheNames) { - return Promise.all(allCacheNames.filter(function(cacheName) { - return cacheName.indexOf(CacheNamePrefix) === 0 && - !(cacheName in CurrentCacheNamesToAbsoluteUrl); - }).map(function(cacheName) { - return caches.delete(cacheName); - }) - ); - }); - }).then(function() { - if (typeof self.skipWaiting === 'function') { - // Force the SW to transition from installing -> active state - self.skipWaiting(); - } - }) - ); -}); - -if (self.clients && (typeof self.clients.claim === 'function')) { - self.addEventListener('activate', function(event) { - event.waitUntil(self.clients.claim()); - }); -} - -self.addEventListener('message', function(event) { - if (event.data.command === 'delete_all') { - console.log('About to delete all caches...'); - deleteAllCaches().then(function() { - console.log('Caches deleted.'); - event.ports[0].postMessage({ - error: null - }); - }).catch(function(error) { - console.log('Caches not deleted:', error); - event.ports[0].postMessage({ - error: error - }); - }); - } -}); - - -self.addEventListener('fetch', function(event) { - if (event.request.method === 'GET') { - var urlWithoutIgnoredParameters = stripIgnoredUrlParameters(event.request.url, - IgnoreUrlParametersMatching); - - var cacheName = AbsoluteUrlToCacheName[urlWithoutIgnoredParameters]; - var directoryIndex = 'index.html'; - if (!cacheName && directoryIndex) { - urlWithoutIgnoredParameters = addDirectoryIndex(urlWithoutIgnoredParameters, directoryIndex); - cacheName = AbsoluteUrlToCacheName[urlWithoutIgnoredParameters]; - } - - var navigateFallback = '/index.html'; - // Ideally, this would check for event.request.mode === 'navigate', but that is not widely - // supported yet: - // https://code.google.com/p/chromium/issues/detail?id=540967 - // https://bugzilla.mozilla.org/show_bug.cgi?id=1209081 - if (!cacheName && navigateFallback && event.request.headers.has('accept') && - event.request.headers.get('accept').includes('text/html') && - /* eslint-disable quotes, comma-spacing */ - isPathWhitelisted([], event.request.url)) { - /* eslint-enable quotes, comma-spacing */ - var navigateFallbackUrl = new URL(navigateFallback, self.location); - cacheName = AbsoluteUrlToCacheName[navigateFallbackUrl.toString()]; - } - - if (cacheName) { - event.respondWith( - // Rely on the fact that each cache we manage should only have one entry, and return that. - caches.open(cacheName).then(function(cache) { - return cache.keys().then(function(keys) { - return cache.match(keys[0]).then(function(response) { - if (response) { - return response; - } - // If for some reason the response was deleted from the cache, - // raise and exception and fall back to the fetch() triggered in the catch(). - throw Error('The cache ' + cacheName + ' is empty.'); - }); - }); - }).catch(function(e) { - console.warn('Couldn\'t serve response for "%s" from cache: %O', event.request.url, e); - return fetch(event.request); - }) - ); - } - } -}); - - - - diff --git a/docs/src/api-console-app.html b/docs/src/api-console-app.html deleted file mode 100644 index a8efd33fc..000000000 --- a/docs/src/api-console-app.html +++ /dev/null @@ -1,133 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/src/api-console-styles.html b/docs/src/api-console-styles.html deleted file mode 100644 index e62a347f5..000000000 --- a/docs/src/api-console-styles.html +++ /dev/null @@ -1,260 +0,0 @@ - - - - - \ No newline at end of file diff --git a/docs/src/docs.html b/docs/src/docs.html deleted file mode 100644 index b18211aaa..000000000 --- a/docs/src/docs.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/docs/src/request.html b/docs/src/request.html deleted file mode 100644 index 0597677b5..000000000 --- a/docs/src/request.html +++ /dev/null @@ -1,47 +0,0 @@ - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/src/shared-styles.html b/docs/src/shared-styles.html deleted file mode 100644 index 253c52565..000000000 --- a/docs/src/shared-styles.html +++ /dev/null @@ -1,11 +0,0 @@ - - - - - - - \ No newline at end of file diff --git a/docs/src/view404.html b/docs/src/view404.html deleted file mode 100644 index ca5170c6b..000000000 --- a/docs/src/view404.html +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/docs/theming.md b/docs/theming.md new file mode 100644 index 000000000..6c55a9f76 --- /dev/null +++ b/docs/theming.md @@ -0,0 +1,43 @@ +# Styling the API Console + +Theming is based on [CSS variables] and CSS mixins. Basic concepts of using the variables and mixins are described in [Polymer 1.0 styling] documentation. + +Note that the CSS mixins are not standardized and therefore require additional libraries to support it. Polymer has it's own implementation of CSS mixins. + +## Basics + +Basic theme is defined in [api-console-styles.html](../api-console-styles.html) file. Inside you'll find a lot of CSS variables and mixins definitions. + +Each of this definition is used to style one of the elements that has been used to build the API console. Most of the elements (at least elements that contain an UI) has their own accepts some set of variables / mixins that will be applied to element's internal content. + +For example `--raml-path-selector-background-color` variable will be accepted by the `raml-path-selector` element (main navigation element) and applied to the element's background color. + +This way theming is possible for encapsulated web components. Also, most of the variables has element's name prefix for better understanding where given variable / mixin will be applied. + +To start creating your own theme you should be familiar with [ARC elements catalog](https://elements.advancedrestclient.com/). It contains all web components used to build the API console. Here you will find documentation and styling guide for all components. + +So, let's assume you'd like to change a style for the title of the HTTP method in the documentation: + +![Documentation > HTTP method > title](method-title.png "Title of the HTTP method") + +The fastest way to style it is to recognize the custom element that contains this title. Use Chrome DevTools inspector (or any other) to inspect this title element. + +![Source of: Documentation > HTTP method > title](method-title-source.png "Source code of the title of the HTTP method") + +As you can see, this title is hosted by the `` element that can be find in the catalog at https://elements.advancedrestclient.com/elements/raml-docs-method-viewer. From the documentation we can see that there are few methods to style this element: +- `--raml-docs-h1` mixin +- `--raml-docs-method-viewer-title-method-font-weight` variable +- `--arc-font-headline` mixin + +Setting any of above properties in your own style definition will alter this element's styles. + +## Sizing the embeddable element + +The `api-console` must either be explicitly sized, or contained by the explicitly +sized parent. Parent container also has to be positioned relatively +(`position: relative` CSS property). "Explicitly sized", means it either has +an explicit CSS height property set via a class or inline style, or else is +sized by other layout means (e.g. the flex layout or absolute positioning). + +[CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables +[Polymer 1.0 styling]: https://www.polymer-project.org/1.0/docs/devguide/styling