Completely refactor SwaggerResolver to support all sorts of goodness

[Helmsdown]

So I took SwaggerResolver apart and put it back together to support several things. Some of these things were supported to begin with (but definitely not all)

Things I was trying to support with the change:

1. Multiple Json and Yaml spec files that are referenced together (looks like @fehguy had did some work on this at the same time)
2. Relative file, URL, and internal file references
3. Performing the resolution in one pass over the swagger model tree
4. Caching contents of files (remote or relative) and resolved objects to avoid repeating expensive operations
5. Gracefully (as possible) handling conflicting reference names (more on this below)
6. Handling resolutions in all variants of Model, Property, and Parameter (e.g. ArrayModels, ArrayProperty, MapProperty, etc)
7. Handling multiple levels of references (e.g. a RefModel which when resolved has a RefProperty)
8. Separating the resolution logic for one type into is own class to hopefully make it easier to rationalize how that logic works and hopefully make it easier to test
9. Centralize shared logic (caching a value, get the contents of ref, json/yaml deserialization)

As always feedback on my code is appreciated.

A note on the tests

I added JMockit as a test dependency. I hadn't seen any other examples of mocking libraries being used in the other swagger libraries. I am a very big fan of JMockit because it doesn't make me work very hard to mock out classes. Of course this is your codebase and you guys get to decide what the dependencies are. I only ask you take a look at the test classes I wrote and let me know if you have any questions as to how I am using JMockit.

Name Conflicts

I implemented some simple logic to supports "deconflicting" references.

For example:

• A model ref somewhere in the spec to "./path/to/modelA.json"
• A model ref elsewhere in the spec to "./path/to/another/modelA.json"

In order to resolve these, they will both need to go into the #/definitions map. This means you have a some choices:

1. Throw an error and give up
2. Last one wins
3. First one wins
4. Rename subsequent models when you put them in #/definitions

I went with option 4 for now. Let me know your thoughts on this. With any of the options, we should strongly suggest to developers to not have conflicting names (at least until we can have a discussion on whether or not namespaces make sense for swagger specs).

[fehguy]

I'm trying to get this tested, but it looks like the scala-based unit tests are not running. When you cleaned up the pom.xml did you disable the scala-maven plugin from running the tests? It could be an artifact of switching to testng.

[Helmsdown]

I didn't intentionally disable scala tests running. This snippet in swagger-core's base pom file seems to be doing something with testng and scala test. This is missing from swagger-parser's base pom file. Do I need to replicate this?

[fehguy]

I'm thinking the testng is causing it:

/~https://github.com/swagger-api/swagger-parser/blob/master/modules/swagger-parser/src/test/scala/RemoteUrlTest.scala#L9

@RunWith(classOf[JUnitRunner])
class RemoteUrlTest extends FlatSpec with Matchers {
  it should "read a remote URL" in {
    val output = RemoteUrl.urlToString("http://petstore.swagger.io/v2/pet/1", null)
    output should not be (null)
  }

I'll see if we can get it to run with testng. I don't think it'll do both junit and testng at the same time without some configuration.

[fehguy]

@Helmsdown I fixed the tests in 5acd565

Once we port the tests to java we can remove this.

[Helmsdown]

@fehguy Most appreciated!