mulesoft / api-console Goto Github PK
View Code? Open in Web Editor NEWAn interactive REST console based on RAML/OAS files
License: Other
An interactive REST console based on RAML/OAS files
License: Other
We are trying to setup the console to run continuously and automatically refresh the RAML from the repo. It would be nice to pass the location via GET:
http://console:9000/?location=api/main.raml
http://console:9000/?location=http://corsenableddomain.com/api.raml
http://console:9000/#location=api/main.raml
Whatever is more convenient.
Can anybody help me to host this console within tomcat ?
Hey all! I'm relatively new to RAML, but have an idea I'd like to throw out. Currently, the RAML console can be "seeded" with a RAML file by either a query string parameter, form field, or the iframe method.
I have something in mind that could help when using the console as RAML is being developed OR when the console is running on a server for users to view.
In particular, it seems like it would be useful to be able to pass in a path for a RAML file when the server is created. For example, grunt server --raml=http://mydomain.com/docs.raml
or grunt server --raml=/some/local/path/docs/raml
. That latter allowing a local file to be easily passed in during development.
Does this fly in the face of other functionality? At first glance, it doesn't appear that there is anything similar in place.
The RAML spec v0.8 allows for a description
on each security scheme.
Unfortunately, this is not reflected in the api-console when selecting an Authentication mode.
On some APIs the actual required values are not implicit when looking at a standard authentication type (i.e. in the Parse API), thus i believe it will be quite useful to display the description
value.
Actually: Building on the parse api example, it would be even more favorable to also have an ability to provide descriptions on the expected input parameters, i.e. defining more exactly what an API expects for username
and password
in a BasicAuth-Scheme. Not sure - is that possible with RAML v0.8 at all?
Query parameters should be displayed either in the parameters tab or somewhere in the verb's documentation. Currently it's not displayed anywhere and the user should have the possibility to see that information.
title: Employees API
version: v0.2
baseUri: http://localhost:9091/api/
documentation:
- title: Employees
content: |
Welcome to the Employees API Documentation. The Employees API
allows you to view a complete list of your employees. You may also
add or delete employees to keep the list up to date.
- title: Contact
content: |
If you need support, please contact [email protected].
- title: More info
content: !include more_info.txt
/employees:
name: Employees
get:
summary: Get a list of employees.
description: |
The employees returned will display the following data: First Name,
Last Name and Birth Date.
queryParameters:
firstName:
description: |
First Name of the employee. This value is not required.
type: string
required: no
example: "Joseph"
lastName:
description: |
First Name of the employee. This value is not required.
type: string
required: no
example: "Joseph"
responses:
200:
body:
application/json: !!null
text/xml: !!null
404:
description: Resource not found.
405:
description: Method not allowed.
415:
description: Unsupported media type.
406:
description: Not acceptable.
400:
description: Bad request.
It would be great if the API console could detect binary content types and not try to render them in a textual format. Having this issue right now with image/jpeg
.
Now, it is still interesting to try such things via the API console, but the presentation format could differ. A simple implementation could show a message that the server's response is in a binary format and/or too large for a preview.
When trying to use post, the following error is displayed:
Response
REQUEST URL
http://localhost:9091/api/employees/1
RESPONSE CODE
500
RESPONSE HEADERS
connection close
content-length 129
content-type application/json;charset=UTF-8 application/json
date Tue, 23 Jul 2013 13:39:42 -0300
http.status 500
server Mule EE Core Extensions/3.4.0
x-mule_encoding UTF-8 application/json
RESPONSE BODY
Could not read InputStream. (org.mule.api.transformer.TransformerException). Message payload is of type: ContentLengthInputStream
THE PROBLEM IS THE CONTENT TYPE VALUE:
Content-Type:application/json;charset=UTF-8 application/json
IT SHOULD BE
Content-Type:application/json;charset=UTF-8
OR JUST
Content-Type:application/json
Below, the yaml used:
title: Employees API
version: v0.2
baseUri: http://localhost:9091/api/
documentation:
- title: Employees
content: |
Welcome to the Employees API Documentation. The Employees API
allows you to view a complete list of your employees. You may also
add or delete employees to keep the list up to date.
- title: Contact
content: |
If you need support, please contact [email protected].
- title: More info
content: !include more_info.txt
/employees:
name: Employees
get:
summary: Get a list of employees.
description: |
The employees returned will display the following data: First Name,
Last Name and Birth Date.
queryParameters:
firstName:
description: |
First Name of the employee. This value is not required.
type: string
required: no
example: "Joseph"
lastName:
description: |
First Name of the employee. This value is not required.
type: string
required: no
example: "Joseph"
responses:
200:
body:
application/json:
example: !include employees.json
404:
description: Resource not found.
405:
description: Method not allowed.
415:
description: Unsupported media type.
406:
description: Not acceptable.
400:
description: Bad request.
/{employeeId}:
name: Employee
get:
summary: Get a particular employee.
responses:
200:
body:
application/json:
example: !include employees.json
404:
description: Resource not found.
405:
description: Method not allowed.
415:
description: Unsupported media type.
406:
description: Not acceptable.
400:
description: Bad request.
post:
summary: Create a new employee.
body:
text/xml: !!null
application/json:
schema: !include employee_insert.json
responses:
202: !!null
404:
description: Resource not found.
405:
description: Method not allowed.
415:
description: Unsupported media type.
406:
description: Not acceptable.
400:
description: Bad request.
jsons included in yaml:
{ "$schema" : "http://json-schema.org/draft-03/schema",
"id" : "http://jsonschema.net",
"properties" : { "birthDate" : { "id" : "http://jsonschema.net/birthDate",
"required" : false,
"type" : "string"
},
"employeeId" : { "id" : "http://jsonschema.net/employeeId",
"required" : false,
"type" : "number"
},
"firstName" : { "id" : "http://jsonschema.net/firstName",
"required" : false,
"type" : "string"
},
"lastName" : { "id" : "http://jsonschema.net/lastName",
"required" : false,
"type" : "string"
}
},
"required" : false,
"type" : "object"
}
{ "$schema" : "http://json-schema.org/draft-03/schema",
"id" : "http://jsonschema.net",
"properties" : { "birthDate" : { "id" : "http://jsonschema.net/birthDate",
"required" : false,
"type" : "string"
},
"firstName" : { "id" : "http://jsonschema.net/firstName",
"required" : false,
"type" : "string"
},
"lastName" : { "id" : "http://jsonschema.net/lastName",
"required" : false,
"type" : "string"
}
},
"required" : false,
"type" : "object"
}
Currently, if your API ONLY supports authenticated calls (and not anonymous) you are still shown on the API Console this option on the try it section, and this is misleading to developers using the console.
This is because in app/views/security_schemes.tmpl.html the line 8
<toggle-item heading="Anonymous"></toggle-item>
is hard coded to always show anonymous regardless of API configuration, and the only way to disable this is deleting the line on the source code... this should be configurable or it should be shown only when NO security (secure_by) is defined for the service.
this is causing signature not matching with other library trying to authenticate requests.
GET&http%3A%2F%2Flocalhost%3A8080%2Fimage-discovery-services%2Fapi%2Ftrs%2Fv1%2Fresolve%2Fsearch_movie&oauth_consumer_key%2Cc699a675ed4b813ca4c44d8feac3262a0a5ff67eb88b1c01b79db4dfec345b6b%2Coauth_nonce%2Cadc99bbfc7e15b2b53b5ec7e2250131b%2Coauth_signature_method%2CHMAC-SHA1%2Coauth_timestamp%2C1403222645%2Coauth_version%2C1.0%2Cw%2Cgladiator
GET&http%3A%2F%2Flocalhost%3A8080%2Fimage-discovery-services%2Fapi%2Ftrs%2Fv1%2Fresolve%2Fsearch_movie&oauth_consumer_key%3Dc699a675ed4b813ca4c44d8feac3262a0a5ff67eb88b1c01b79db4dfec345b6b%26oauth_nonce%3Dc4e9dadd7baf72ea9d363d70adf273c3%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1403220735%26oauth_version%3D1.0%26w%3Dgladiator
...
Running "copy:dist" (copy) task
Copied 3 files
Running "copy:embedded" (copy) task
Copied 20 files
Running "cdnify:dist" (cdnify) task
Warning: Unable to read "bower.json" file (Error code: ENOENT). Use --force to continue.
Aborted due to warnings.
When you open a method documentation, and it's too long, the scrolling does not work.
I put up a copy of this project on heroku today to demonstrate the issue:
If I put in https://raw.githubusercontent.com/kevinrenskers/raml2html/master/example.raml
The URL, it does not work. I've also tried using http://pastie.org with raw content and it also fails.
Furthermore, it would be nice if something like: http://raml.herokuapp.com/?raml_location=https://raw.githubusercontent.com/kevinrenskers/raml2html/master/example.raml
Actually worked so I could share a link to documentation with people directly.
According to the specification, a response may contain a description (see below), but the api-console parser fails when there is such an element.
From http://raml.org/spec.html:
/media/{mediaid}/content:
displayName: Content
get:
description: |
Get a media file.
responses:
200:
body:
"/":
description: |
Returns the media file.
Responses MAY contain a description property that further clarifies why the response was emitted. Response descriptions are particularly useful for describing error conditions.
See raml forum for description and reproduce scenario
http://forums.raml.org/t/keep-getting-404-in-api-designer/191
do we need to have bower_components inside /app/vendor
i could see this directory missing.
This is a minimal example of the problem. I have the following RAML file:
#%RAML 0.8
title: sample
baseUri: http://localhost/
version: v1
mediaType: application/json
/pages:
get:
headers:
link:
repeat: true
type: string
After I try to render it in a "Try it" tab, the "link" header is rendered with a little "plus" sign next to it, so that it can be multiplied, to provide multiple values.
However, as soon as I add second header by pressing this "plus" sign, the second header gets the same value as the first header, and whichever input field I modify, the other gets modified as well. This makes the feature completely unusable.
We are using zero legged oauth-1 . Can anybody tell how to disable all the token calls
/oauth/1/request_token/
/oauth/1/authorize/
/oauth/1/access_token/
I just need signature generation using consumerkey and consumersecret
I am running mule locally (survivor:8095) and api-console locally (localhost:9000). As a comparison I also have the console available from the mule application. When I try an example request using the mule hosted console I get a 201 as desired. However when I try the same request from the stand-alone api-console I recieve the following error:
Cannot POST /proxy/http://survivor:8095/prioritisation/api/jobs
Looking in the mule logs I get:
2014-06-02 15:38:48 WARN Router:265 - No matching patterns for URI
So the request is reaching the mule REST service but for some reason it can't match the request. I'm a bit stumped as to how this is?
This is affecting the unit tests. We must make sure that this does not have an impact on cross browser issues.
I'm not sure if this is possbile.
It'd be great if we could expand the schemas completely.That is, expand "$ref" keys to other schemas inline.
title: Employees API
version: v0.2
baseUri: http://localhost:9091/api/
/employees:
name: Employees
get:
description: |
The employees returned will display the following data: First Name,
Last Name and Birth Date.
responses:
200: !!null
If a method is defined as optional in one resource type and then inherited by another resource type, with the 'type' keyword, that also defines the same method as optional, then that method appears to no longer be optional. The api-console displays all resources defined with the child type to have that method. Optional methods should stay optional if it is optional through out the entire list of inherited resource types.
A minimal example:
#%RAML 0.8
---
title:
resourceTypes:
- common:
get?:
- base:
type: common
get?:
/files:
type: base
Here /files will be shown to have a GET method when it should not.
It would be useful to be able to send someone a link to a specific resource/method.
The license under which the API console is released requires attribution in any UI presented by the code. Please add the "Powered by Mulesoft" logo to help users comply with the license requirements.
I've cloned this repo and deployed the dist in a Tomcat engine.
I've found three (serious) usability issues with the single page model.
On the initial screen, I enter the URL of a RAML doc and select [LOAD FROM URL] After exploring it a bit, I go to my (external) editor and update/save the RAML.
To refresh in the API Console, I cannot use the browser Back button; I must refresh the page. This is very unintuitive as the initial button feels like a submit. Further, when I refresh, the URL field is empty and I have to copy/paste the URL again to refresh. If this worked more like a submit/back, this would be much easier to use.
Also, if there is a syntax error in the RAML, I get back a display of some unformatted JSON with the error message inside it, and this is hard to decipher. It would be better to list the error message and line number, then show the RAML and highlight the error.
Finally, if instead of pasting in a RAML URL, if I paste in full RAML then select [ LOAD RAML] to try it out, again I can't use the browser Back button to return to my RAML source and edit it. If I refresh the page, the RAML source is gone. Again, a Submit/Back user experience would be much better.
[Yes, I know I can use RAML API Designer but its persistence model does not work well with other toolchains, alternate source layouts such as using a schemas/ subdirectory for ll schema files... in fact I can't get it to recognize .xsd schema files ]
I believe there is another request to allow passing the RAML URL to API Console startup - a query parameter would be very useful if I could refresh to reload.
When entered a valid URL to a RAML file:
{"context":"while fetching http://localhost:8000/api.raml","context_mark":null,"message":"cannot fetch http://localhost:8000/api.raml (Error: NETWORK_ERR: XMLHttpRequest Exception 101)","problem_mark":null,"line":11795,"sourceURL":"http://localhost:9000/vendor/raml-parser.js","stack":"fetchFile@http://localhost:9000/vendor/raml-parser.js:11795:128\nreadFile@http://localhost:9000/vendor/raml-parser.js:11757:30\nhttp://localhost:9000/vendor/raml-parser.js:11704:30\napply@http://localhost:9000/vendor/raml-parser.js:1793:31\npromiseDispatch@http://localhost:9000/vendor/raml-parser.js:1432:46\nhttp://localhost:9000/vendor/raml-parser.js:2044:40\nflush@http://localhost:9000/vendor/raml-parser.js:877:21\nhttp://localhost:9000/vendor/raml-parser.js:740:23"}
Is there any way to load the api console and have it pull the "Load From URL" value in through the URL as a get argument? I would like to have a link to the API console which will load my RAML file automatically without having to paste it into the "Load From URL" box and submitting that data.
Thanks
Console does not display actions for a nested resource. The actions are available from another rest console (e.g. postman).
E.g.: http://localhost:9091/api/employees/{employeeId}/sons/{sonId}
We can define the expected request body through RAML and I think that the console could provide some kind of template based on the JSON schema (of course only if some JSON content type is selected).
Example:
I have the following very basic JSON Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "collection_command",
"description": "Writable collection representation",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": ["name"],
"additionalProperties": false
}
I switch to 'Try It' in the web console and choose application/json
as my content type. The web console automatically inserts the following basic template:
{
"name": "TODO",
"description: "TODO (optional)"
}
Now I don't propose to go crazy about this and support the vast amount of features that JSON schema supports, e.g. patternProperties, but a simple template generation for named properties (given the schema type is object
) is possible.
Thinking further: This could even be extended to other schema types (XML), but I believe that JSON schemas would be a good place to start.
I would be willing to contribute if you find this feature acceptable for the api-console project.
We secure our api using OAuth 2.0 using client credentials but I can't get it to work using the 'Try It' functionality in api-console.
The RAML spec says that the authorization grants can be any of: code, token, owner or credentials but I get a javascript error when I try to use credentials that says the authStrategy is undefined. My javascript isnt amazing but the GRANTS array in the OAuth 2 section (https://github.com/mulesoft/api-console/blob/master/dist/scripts/app.js#L720) it only has code and token. If I use code or token I do not get the same js error.
Am I missing something or is client creds unsupported?
Thanks
When having the following config:
title: Employees API
version: v0.2
baseUri: http://localhost:9091/api/{version}/{company}
uriParameters:
company:
name: Company
type: string
minLength: 0
maxLength: 10
required: yes
global parameters are not being considered.
This looks like a bug.
How to reproduce:
queryParameters
.enum
property for a new query parameter. get:
queryParameters:
test:
description: test the enum property
enum: [Test1,Test2]
3 if the test
parameter is set for example to Test1
, the client makes a call like GET /test
Expected :
GET /test?test=Test1
When I use the console to 'get' a resource the response is displayed into the delete tab
#%RAML 0.8
---
title: ANY API
version: 1
baseUri: /api
/resource/{resourceId}:
get:
description: Get the content of a resource.
post:
description: Create a resource.
delete:
description: Delete a resource.
title: Employees API
version: v0.2
baseUri: http://localhost:9091/api/
/employees:
name: Employees
get:
description: |
The employees returned will display the following data: First Name,
Last Name and Birth Date.
responses:
200: !!null
Given the following yaml:
title: Employees API
version: v0.2
baseUri: http://localhost:9091/api/
/employees:
name: Employees
get:
responses:
200: !!null
/{employeeId}:
name: Employee
get:
responses:
200: !!null
Going to /employees/{employeeId} should enforce that an id should be specified.
Right now it is not being validated, and it retrieves all employees (same as get:/employees/).
When there is a required query parameter, there is no way to differentiate them from not required parameters. There should be something
More like an enhancement - not everyone in this world is using node.js or is willing/allowed to have all its related mumble-jumble installed on the infrastructure servers.
What would be really nice is to have a CLI command to generate static documentation (similar to https://readthedocs.org, as example). The feature of "Try it" can also be included and rely on a proxy, which settings would be provided before generation.
I'm willing to contribute, but not with the current stack used for implementation :-(
I have api-console running on the same box as an NGINX proxy server (which proxies our APIs to circumvent CORS issues).
The 'Try It' feature works fine. . .
unless I pass a URL to the proxy with query params. It appears that the query params are getting stripped out by api-console because the 'Request URL' under 'Response' shows with the query params stripped out. Of course, this results in a 404. . .
oh yes, NGINX is setup to forward along query params. . .
Enum not usable on Headers
#%RAML 0.8
---
title: ANY API
version: 1
baseUri: /api
/resource/{resourceId}:
get:
description: Get the content of a resource.
headers:
Accept:
enum:
- application/json
- text/html
After a while of figuring out that I can't use try it, if I'm using a custom security schema, I'm all ready to go and fork the project to implement the changes required - but then I saw that there's a new version of console coming out soon? I see the features/console-2.0 branch too - should I be trying to add this functionality to the existing console or should I try out console v2? Does console v2 already have this functionality?
Thanks!
Really happy getting my api accessible via console, having the full code completion features available is quite nice, however i find myself deleting whole code blocks without intent while just wanting to delete the last word when i hit CTRL+BACKSPACE
.
For one, technically this is a different from CTRL+DELETE
.
For worse, it breaks consistent user experience (I heavily rely on this "move" ;) and basically have been relying blindly on it for years) - whereever there's a gui notepad, office document editor, code IDEs, address bar urls and most importantly Text-Boxes on HTML WebForms all behave this way; no matter whether on Windows or KDE
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.