[lsiebert]

This is good advice, though I'd note that Swagger unfortunately can't match up exactly JSON api (in the jsonapi.org sense).