swagger.json generated by the example has errors

[jbockerstette]

Swagger generation doesn't seem to work correctly. The generated swagger.json contains may errors from the example project.

In order to debug this problem, I eliminated all the resources except for the people.js resource. In addition, I got rid of references to the other resources in the people.js file.

I then used the swagger editor to fix the problems found in the resulting swagger.json

I am providing the links to my people.js file : https://drive.google.com/file/d/0BzXg1kzQ457OeHpUMVhtVDk2MEk/view?usp=drivesdk

Here is the swagger.json file that was generated: https://drive.google.com/file/d/0BzXg1kzQ457ONDlVZUZZOElZdUE/view?usp=drivesdk

Here is the swagger.json file that I fixed using the Swagger editor: https://drive.google.com/file/d/0BzXg1kzQ457ORVdpdGlQRU90bVk/view?usp=drivesdk

[theninj4]

Thanks for reporting this, I'll take a look and sort it out 👍

[jbockerstette]

Here is one fix, but there are more:
lib/swagger/paths.js line 119
required: [ "jsonapi", "meta, links" ],
Should be
required: [ "jsonapi", "meta", "links" ],

[theninj4]

I'm going to investigate adding another step to the CI to validate the swagger output on each build, just in case we introduce any regressions in the future.

[jbockerstette]

If you do a diff on these two files, you will see where all the changes that I made to fix my swagger.json.
In my swagger.json, there are 4 error types and 1 warning which are repeated over and over. So even though I had to make a lot of changes, there are really only 4 bugs and 1 warning.

I am adding these files
swagger_json_broken.txt
swagger_json_fixed.txt

because there is additional errors that you would not see in my first report.

[theninj4]

Thanks @jbockerstette - I think I've fixed all of the bugs, and cleaned up the required attributes. There's also a CI build task that will validate the generated swagger docs, which should help prevent this from happening again.

[jbockerstette]

You're awesome. Great job. Is there some way to configure the required
attributes so they only show up if you want them?
On May 21, 2016 3:52 AM, "Oliver Rumbelow" notifications@github.com wrote:

Thanks @jbockerstette https://github.com/jbockerstette - I think I've
fixed all of the bugs, and cleaned up the required attributes. There's
also a CI build task that will validate the generated swagger docs, which
should help prevent this from happening again.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#129 (comment)

[theninj4]

Thanks :)

The required attributes come from the Joi schema in the resource definition, for example in https://github.com/holidayextras/jsonapi-server/blob/master/example/resources/articles.js we have:

attributes: {
    title: jsonApi.Joi.string().required()
      .description("The articles title, should be between 8 and 15 words")
      .example("Learning how to use JSON:API"),
}

Notice the .required() - the generated Swagger document will require those attributes marked as required. You can tag attributes however you like, and all models passing through to your handlers are validated against the schema.

[jbockerstette]

Ok. I was playing with that but no matter what I tried, it always put the
required flag in my swagger. I will try again now that you have fixed it.
Thanks
On May 22, 2016 11:01 AM, "Oliver Rumbelow" notifications@github.com
wrote:

Thanks :)

The required attributes come from the Joi schema in the resource
definition, for example in
https://github.com/holidayextras/jsonapi-server/blob/master/example/resources/articles.js
we have:

attributes: {
title: jsonApi.Joi.string().required()
.description("The articles title, should be between 8 and 15 words")
.example("Learning how to use JSON:API"),
}

Notice the .required() - the generated Swagger document will require those
attributes marked as required. You can tag attributes however you like, and
all models passing through to your handlers are validated against the
schema.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#129 (comment)

[theninj4]

The changes have been merged and pushed to NPM as v1.7.0 👍