The swagger-editor's discuss from swagger-api

structural issue in consolidated format

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);
}

Include assets for YAML syntax

Includes the default YAML and syntax guide pane.

Move project into swagger org

…assuming we can set one up, otherwise possibly Wordnik org.

Move to new org (do issues move, too?)
Add licensing notice
Update the readme with info and how to participate

Action to download a client sdk

Generated from Tony's service (details to be provided)

Move JSON out of editor and over to html pane

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.

Import an existing Swagger description into YAML

Point the YAML editor to a Swagger endpoint and then generate the YAML as the starting point.

Explore parsing YAML syntax

We need to get access to AST of YAML in order to able to modify the YAML programmatically. Explore our options.

Refactor the YAML syntax

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.

Can't run locally

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

Autocompletion of swagger-yaml

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.

Add codegen support

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:

http://generator.wordnik.com

There are some bugs in the input model right now so the POST methods are not accurate. A proper usage is like such:

generate a java client:

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

generate a objc client:

curl -X POST http://generator.wordnik.com/online/api/gen/client/objc -H "Content-Type:application/json" -d @client.json -o objc-client.zip

generate a jaxrs server:

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:

https://gist.github.com/mohsen1/ec3afcadef5e88a8cb50

Allow definition of re-usable YAML bits

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.

Better resource path YAML syntax

Instead of:

path: "/pet/{petId}"

… it would be nicer to use:
/pet/{petId}

Resolve the conflict between distributed resources

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?

Design error pane

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.

Add Help button to navbar for user guidance

A small button that can provide and context / help to users

Buttons for common tasks

Beginners unfamiliar with the swagger-yaml syntax may benefit from buttons to add path, method, params, and even re-usable params.

Guidance for users unfamiliar with the YAML format

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.

Add delay for refreshing right-hand pane

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.

Persist on text editor's content via localStorage

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).

Enable saving and loading of one's work

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.

Add instructions for building and running locally

The readme should include something like:

Node must already be installed on your local machine.

npm install
bower install
grunt serve

Implement the revised YAML syntax and consolidated json

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#

Compatibiity with Swagger-styling

Today the header is orange, but that isn't necessarily harmonious with the Swagger styles. Petstore is a good example. @fehguy may have guidance here…

Note that Swagger 2 will present a chance to revisit the Swagger style.

Wire up new ace theme

Here's a new theme based on atom-dark, but it needs some @mohsen1 magic to work with 'grunt ship'.

https://github.com/apigee/swagger-editor/blob/master/app/bower_components/ace-builds/src-min-noconflict/theme-atom_dark.js

Live updates to swagger-ui on YAML editor

This is probably already in the works, but right now live edit only works with JSON edits, not YAML.

Remove initial animation

Add a new fav icon

YAML Linting

This story refers to item number 3 below…

There are at least three ways we can help guide users:

Auto-complete. Minimum is the total syntax, best is contextual to the structure's location
Contextual help to offer syntax guidance (could be as simple as an expandable pane or dialog)
Validation of the Swagger-YAML (linting). This is more than just creating valid YAML—it includes checking for required elements, etc.
Buttons such as "add a resource" or "add a method" or "add a query parameter", etc.

The guiding question is, "How do we make authoring the swagger-yaml easy for people who do not yet know the synax?"

Deal with consolidated swagger-json

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, ….

Make a checkbox on header to disable auto render of docs

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

Support fenced blocks of multi-line descriptions, including markdown and/or html

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.

Scroll into-view operation that is being edited currently

When I'm working on the summary of a method, I can't see it unless I expand and navigate to the detail view in the html. Ideally, the html knows where you are in the YAML and updates it automatically.

Example:

When clicking "New", right pane should show "invalid or empty..." message

Clicking on `#!` links in preview will navigate the preview panel to destination of the link

Updating the resourcePath doesn't change the child paths

This may be an issue of redundancy in the Swagger spec, but when I edit the resourcePath, I expect the child paths to update as well. Should the editor do this? Should the spec change?