Full end to end conversion test

[russell]

look at confirming that the conversion of the source to Swaggerish matches our custom Swagger Schema. So we will need to find a schema validator and write a test that migrates all the data and checks it validates.

[kbhawkey]

I would like to help out with validation.

[russell]

I'm thinking that we will need to include the Swagger schema in fairy-slipper somewhere, both Anne and i have had a crack at making a custom schema.

@annegentle seems to have made the most progress https://github.com/annegentle/fairy-slipper/tree/json-schema

Mine is here https://github.com/russell/swagger-spec

When i started making random changes to the swagger that is output I didn't know that swagger supports extensions through using object elements that begin with x- https://github.com/swagger-api/swagger-spec/blob/master/guidelines/EXTENSIONS.md As a result most of the changes to the swagger that i have made should be updated to use this mechanism.

[annegentle]

I'm looking at validation and I think we'll need to "glue" together all the json to make a single swagger.json file per service. Then, we can validate after we get the specific vendor extensions merged, I think I'm calling it x-post-action-pathItem. @kbhawkey I'll keep working on my branch with the vendor extension, merge it, then look at how validation works and help however I can.

[annegentle]

Oh, and my reasoning for a single swagger.json file per service is so that we can use the online validator for nearly all the services: https://github.com/swagger-api/validator-badge

[russell]

Thanks @annegentle, that is cunning to have the our swagger extension kept in a separate file.

I was hoping that we could hook up a validator so we can test the migration and even use it in the intermediate conversion step to help us reduce the divergence of the 2 versions of swagger. From what I can see the online validator requires us to host the swagger.json on a public website. This will be fine, in the future in the AngularJS interface, but it won't work when validating during testing.

There are a couple of JSONSchema validators in python, but realistically one in JS or MVN will be fine too. We can use the subprocess call it in the test if needed.

Ideally we would like to get to the stage where we can round trip the data so swagger.json -> swagger_to_rst.py -> rst files -> fairy-slipper -> swagger.json -> swagger_to_rst.py -> rst files -> fairy-slipper -> swagger.json will give us exactly the same swagger.json we started with. To help us get there the validator will call us out when we don't conform to the schema.

[annegentle]

Okay, and to get the swagger.json glued together, do we need to use json-spec? https://pypi.python.org/pypi/json-spec Or are you already? I don't see a swagger.json file anywhere so far, so I'm looking into it.

[russell]

No we aren't using json-spec currently, but it looks pretty sweet. Initially we probably need 2 things

One will be the original v2 swagger schema and then an auxiliary schema file that contains our addons. I think at that point we can start experimenting with how we validate without storing the merged file. That would be much better in the long run.

Once we have the schemas we can look at adding an initial end-to-end test that migrates then validates the migrated data.

At that point we should probably also look at extending every test case that deals with Swagger JSON to validate too.

[annegentle]

Okay, more notes as I keep working on a separate swagger file, we're finding that you have to have an entire swagger.json in order to validate, and nearly all the tools make it difficult to use $ref to split the large file into smaller ones.

[annegentle]

Ok, what we found while testing a half dozen solutions, is this works to validate Swagger created from multiple JSON files:

Use a deref.js file like this one: https://github.com/jamiehannaford/swagger-magnum/blob/master/deref.js

Install these pre-requisistes:

npm install swagger-parser@alpha
npm install -g json
npm install -g swagger-tools

And then run:

node deref.js && swagger-tools validate -v v1/swaggerFull.json

That'll output a swaggerFull.json file that is built from separate .json files that have the JSON Schema $ref references throughout. Makes it much easier for a human to compare files while also giving a validated Swagger file.

[russell]

I have started to investigate this. I have a partially working validator. I should be able to have it completed in the next couple of days. @kbhawkey if you have started on this please let me know and I'll find something else to do.

[kbhawkey]

Go ahead @russell. I am finishing up issue #25.

[annegentle]

I'm looking at outputting Swagger for most all services, then using the $ref mechanism to extend the services Swagger that uses the POST blah/blah/actions over and over.

[kbhawkey]

Can you elaborate a bit more and point to a specific example of extending a service and what the generated swagger would look like?

[annegentle]

Yep, looking for https://github.com/jamiehannaford/swagger-magnum/blob/master/v1/swagger.json as the output swagger files, with the $ref files also output and then referred to from the swagger.json file.

The extensions for swagger are described here: https://github.com/swagger-api/swagger-spec/blob/master/guidelines/EXTENSIONS.md

What I'm thinking of is this:

using x- for the POST actions https://github.com/annegentle/fairy-slipper/blob/da36d58cbd16e6dec9d8bc15c824f1fc827acd6c/tools/swagger.json#L308

I'll see if I can do a small sample... struggling to code!

[kbhawkey]

Let me know if I can be of help here.

[kbhawkey]

Wrote a version of wadl to swagger which produces valid json for some services and addresses issues #56, #57, #58, #59, #60, #61, #63, #64, #65, #67. Fixes needed for #62, #66. There may be other errors as each file is validated.