swagger-api / swagger-editor Goto Github PK
View Code? Open in Web Editor NEWSwagger Editor
Home Page: https://editor.swagger.io
License: Apache License 2.0
Swagger Editor
Home Page: https://editor.swagger.io
License: Apache License 2.0
Using HTML5 File API make a file bulb and make it downloadable via a button.
related to #25, is the idea of autocompletion. At its simplest, this might be tab-completion of a key name. Even better would be if it could also understand the YAML schema, so that appropriate values could be decided between. ACE has both "snippets" and "autocomplete, see: https://github.com/ajaxorg/ace/wiki/How-to-enable-Autocomplete-in-the-Ace-editor
Snippets example using XSLT: https://github.com/ajaxorg/ace/blob/a4a30b6665da5f5ef9c3bd23d7bac01374bae450/lib/ace/snippets/xslt.snippets
Consider snippets for adding a full now path or method element. Best of all would be if it could pull context from the working doc so that if I've defined a reusable YAML param, then I could choose from the list of those names.
Any ideas why I'd get this message when running locally?
fehguy:phonics tony$ grunt serve
/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/node_modules/findup-sync/lib/findup-sync.js:33
}).flatten().uniq().value();
^
TypeError: Object Gruntfile.js has no method 'flatten'
at Object.module.exports [as findup] (/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/node_modules/findup-sync/lib/findup-sync.js:33:8)
at Task.task.init (/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/lib/grunt/task.js:427:16)
at Object.grunt.tasks (/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/lib/grunt.js:117:8)
at Object.module.exports [as cli] (/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/lib/grunt/cli.js:38:9)
at Object.<anonymous> (/usr/local/lib/node_modules/grunt-cli/bin/grunt:43:20)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
I have the following runtimes:
fehguy:phonics tony$ node --version
v0.10.21
fehguy:phonics tony$ grunt --version
grunt-cli v0.1.11
grunt v0.4.4
When navigating in preview panel, we should collapse the code panel to just show the content related to what's being shown in preview panel.
Swagger-JSON defines the root description with api-doc, such as:
petstore.swagger.wordnik.com/api/api-docs
This tells you the individual resources families that you get a description for each.
YAML should have a unified view of all the description in one file. How to deal with this?
It's great to be able to write YAML with live preview, but we need a way for people to save out their work (to file, local storage, git repo, whatever).
The readme should include something like:
Node must already be installed on your local machine.
npm install
bower install
grunt serve
Guidance from @fehguy:
Updated library which takes consolidated JSON:
https://github.com/wordnik/swagger-js/blob/develop/lib/swagger.js
and corresponding swagger-ui branch:
https://github.com/wordnik/swagger-ui/tree/develop/dist
You can see an example in this test script:
https://github.com/wordnik/swagger-js/blob/develop/src/specs/petstore_1_2_spec.js#L441
Note there is an array of “apiDeclarations” which literally map to the swagger json for each root resource. So if you take this:
http://petstore.swagger.wordnik.com/api/api-docs
add a key “apiDeclarations” with array value containing each of these:
http://petstore.swagger.wordnik.com/api/api-docs/pet
http://petstore.swagger.wordnik.com/api/api-docs/store
http://petstore.swagger.wordnik.com/api/api-docs/user
You’d have the “consolidated JSON”.
When using this with swagger-ui, you simply initialize it as follows:
window.swaggerUi = new SwaggerUi({url: “URL”, obj: THE_SWAGGER_CONSOLIDATED_OBJECT, ….
The killer demo is using the consolidated spec for codegen. It works like this.
There is an online codegen that lives here. It has a swagger description available here:
There are some bugs in the input model right now so the POST
methods are not accurate. A proper usage is like such:
EDIT: this is now on the wordnik domain
curl -X POST http://generator.wordnik.com/online/api/gen/client/java -H "Content-Type:application/json" -d @client.json -o java-client.zip
curl -X POST http://generator.wordnik.com/online/api/gen/client/objc -H "Content-Type:application/json" -d @client.json -o objc-client.zip
curl -X POST http://generator.wordnik.com/online/api/gen/server/jaxrs -H "Content-Type:application/json" -d @server.json -o jaxrs-server.zip
client.json
:
When the YAML syntax is incorrect we hide documents and show an error pane. Please design the error pane with some icons and fonts. You can find the html file at invalid-docs.html.
Beginners unfamiliar with the swagger-yaml syntax may benefit from buttons to add path, method, params, and even re-usable params.
Work with @MMux to allow for whatever should happen when you hover or click the swagger icon.
Instead of:
… it would be nicer to use:
/pet/{petId}
Longer descriptions will eventually be necessary. The right way to handle this may be by fencing with ``` and then processing any markdown and/or html. This is out of scope for May.
Put a checkbox on header for disabling auto rendering of docs.
Checkbox label should say "Auto-generate docs"
Initial state should be checked
By unchecking it auto generation of docs will be stopped and docs panel go dim
By checking it, docs get generated automatically and preview panel will un-dim
…assuming we can set one up, otherwise possibly Wordnik org.
Work with @MMux to resolve the header height, colors, etc.
There will be many people who do not know the syntax for Swagger-YAML. We can help them with approaches like a syntax list on the right-hand pane, autocomplete, and/or buttons to "add a resource" or "add a method" or "add a query parameter", etc.
YAML has reusable bits that get rendered into JSON. The problem is that is lossy—there isn't an easy way to preserve the relationship of the JSON back to the original definition. This has potential to complicate the 2-way editing process (as does the multiple file aspect of JSON).
Instead, let's move JSON out of the edit pane and over to the swagger-ui pane. Then you can see the docs or switch to the JSON view.
seems like the YAML 2 JSON process is not processing merges or anchors
If you do work, you need a way to save and restore it. This could be done in localstorage, or it could be a github repo/gist integration, or it could be the filesystem.
Here's a new theme based on atom-dark, but it needs some @mohsen1 magic to work with 'grunt ship'.
Includes the default YAML and syntax guide pane.
For example, editing the "resourcePath" doesn't update the child APIs' paths. Also, the "path" could be a top-level element rather than a child of "apis".
Marsh and Tony will work this out.
SwaggerUI has it's own navigation router system. Manage to integrate that routing system into our app.
For example #!/pet/deletePet
should be translated to /#/pet/deletePet
Consider an approach more like jsbin where you can toggle multiple panels. This might include:
As you edit in YAML, the JSON would update, and vice versa (except for the reusable bit, need to think about that)
We like to have more specs on top of JSON specific specs. For example renamed keys in YAML. Those keys would get translated during YAML-to-JSON conversion
@earth2marsh please write specific key names we need to translate to generate JSON
We need to get access to AST of YAML in order to able to modify the YAML programmatically. Explore our options.
Right now, when you start typing, the swagger-ui blanks out and tries to redraw. This can be jerky.
Instead, try leaving the swagger-ui in place until there hasn't been a keystroke for 500ms. Then draw the update.
This should solve the "jerkiness" and may enable us to remove the "live update" button.
This is probably already in the works, but right now live edit only works with JSON edits, not YAML.
A small button that can provide and context / help to users
In addition to the single, unified YAML file (whereas JSON is # of resources plus the root doc) and in re-usable YAML definitions, we'll want to consider any YAML-specific names. See: https://docs.google.com/a/apigee.com/document/d/1hrovNL4VQl0sUa5eLnFuoNcYVxu86LvS1z6wXJOkTOg/edit#
Generated from Tony's service (details to be provided)
No need to try it when the API is being designed and doesn't exist yet! In the short term, remove the try-it button and hide the auth config.
Not necessary for the POC, but at some point we need to warn folks about losing their work when they try to do things like close their tab or reload their page.
If you look at existing consolidated format, the apiDeclarations
key is at the same level as apis
. In the default YAML, it's at the top level.
See here for what is expected:
https://gist.github.com/fehguy/e3e20da90179b1027480#file-gistfile1-yml-L33
The fix is easy:
line 56, main.js should be:
if(json && Array.isArray(json.model.apiDeclarations)){
$scope.apiDeclarations = json.model.apiDeclarations.map(buildapiDeclarationDocs);
}
Point the YAML editor to a Swagger endpoint and then generate the YAML as the starting point.
Swagger's YAML generator does support re-usable YAML bits that can then be referred to later. We should support this and allow creation of those reusable snippets.
This story refers to item number 3 below…
There are at least three ways we can help guide users:
The guiding question is, "How do we make authoring the swagger-yaml easy for people who do not yet know the synax?"
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.