Update to Swagger 1.2. Fixes #11, #8, #7.

[STRML]

Changes in this PR:

• Moved public (swagger UI) out of this module and required swagger-ui as a module in package.json.
• Added swaggerDistRoot option so users of the API Explorer can override any part of the UI (styles, JS, HTML).
• Compatibility with Swagger 1.2 (spec) (transition guide)
• Model schemas are now correctly populated.
• An accessToken can be provided via the header input.

When this is merged, it should be safe to remove strong-remoting/ext/swagger, the associated test, and app.docs().

Fixes #7, #8, #11.

[slnode]

Can one of the admins verify this patch? To accept patch and trigger a build add comment ".ok\W+to\W+test."

[raymondfeng]

@STRML, thank you for the patch. This is a great improvement to our API explorer experience. I started to play with it and a few issues are fixed at:

https://github.com/strongloop/loopback-explorer/tree/STRML-feature/swagger1.2

The PR also exposes some requirements to strong-remoting. For example, the accepts/returns argument should have a way to reference the declaring model as the type. Let's try to create issues as we go.

[STRML]

Ok. I've done a little bit of cleanup for array items. I'll create corresponding issues in strong-remoting and link them back here.

[bajtos]

@slnode add to whitelist

[raymondfeng]

@STRML We are losing the CSS customization made by loopback-explorer. Is there a way to add it back?

[STRML]

@raymondfeng Yes, any loopback-explorer overrides of swagger-ui go in /public. I will find the old customizations & restore them.

[STRML]

@raymondfeng I've replaced the old styles.css and supporting files in 45172da. At some point someone should go through it and move the individual overrides out.

[bajtos]

I did a quick read through the patch, I am impressed, especially about the comments. I'd like to do a more detailed review tomorrow.

There is one idea we had with @ritch connected to the migration of swagger code from strong-remoting to loopback-explorer: change the way how resource descriptors are exposed - use regular express routes instead of building a virtual shared object & shared methods. Reasoning: at the moment, loopback-explorer is modifying the application by adding more remotable objects. This also means that to access swagger descriptors, one has to pass the authentication layer configured for regular models. We had to add a patch to loopback to fix this (see lib/application.js).

@STRML what's your opinion on this idea? Do you agree? Does it make sense to make the change as part of this pull request, or would you rather leave it for later?

[raymondfeng]

@STRML Fantastic! I was able to bring up the new explorer with existing application. The changes are merged into https://github.com/strongloop/loopback-explorer/tree/STRML-feature/swagger1.2. Would you like to rebase from it to avoid future merging conflicts?

[STRML]

@bajtos I agree. That should be easy to fit into this patch. I'll update shortly.
@raymondfeng Thanks - will rebase as your commit is good context as to why body is not ignored. I need to reformat the commit messages, however, and will update this PR.

[STRML]

@bajtos I've completed that change. It significantly reduces the complexity of the implementation. Review when ready. 👍

[bajtos]

This is not entirely true. Types can be specified both by constructors (String) and type names (object).

[bajtos]

I think you misunderstood my comment. The idea was to not modify the route, but return the accepts in the format needed by swagger.

var accepts = routeHelpers.convertAcceptsToSwagger(route, classDef);

var apiDoc = {
  // ...
  parameters: accepts.map(routeHelper.acceptToParameter(route))
  // ...
}

An even better solution may be to call acceptToParameter from hackAcceptsDefinition.

function buildParameters(route) {
  // add ctor arguments
  // filter out computed arguments
  // for each argument: convert the type to Swagger, convert the argument to Swagger parameter
}

// later
var apiDoc = {
  // ...
  parameters: buildParameters(route)
  // ...
}

Anyways, I guess this is rather subjective. If you don't think my proposal will make the code better or you don't think it is worth the effort, I can live with the current version too.

[bajtos]

I left few more comments, the patch is almost good to be merged. I'd like to test it a little bit before giving it a green light.

[STRML]

@bajtos Addressed your comments; should be good to go.

[raymondfeng]

loopback-explorer works with loopback 1.x which depends on express 3.x. Can we make it compatible with loopback 1.x & 2.x?

[bajtos]

AFAIK express 4.x apps have the same public api as the 3.x apps, i.e. function(req, res), thus this change was not strictly necessary.

[STRML]

@raymondfeng Thanks for the comments, fixed.

[bajtos]

The code LGTM. Unfortunately I don't have time to test the new explorer myself, I'll leave the final sign-off to Raymond.

Thank you @STRML for your contribution, I appreciate the effort you put into this patch and how quickly you addressed our comments.

[raymondfeng]

The authorization key name should be access_token.

[raymondfeng]

@STRML please fix the last issue I raised above. We're good to go after that. Thanks!

[STRML]

Good to go, merge when ready.

[STRML]

Thanks, everyone, for helping me get this merged and available to all of loopback's users!