API improvements meta issue

I've opened a relatively large number of PRs, so I though I'd create this issue for feedback that applies across all of them (or so you can tell me to bugger off).

First off, I'm glad that there is an example API for OpenAPI. It's a good to have a reference for how to use the format, and with OpenAPI's popularity provides a good way for people to implement the same API in different languages/stacks.

I was initially intending to implement the API myself but ran into a number of things that made it unclear how to proceed or that just didn't make sense. I've opened several issues to address a number of those issues, as well as some that reflect a preference that I think is somewhat close to a best practice.

Issues are as below

46 - remove unused models
47 - make query parameter format reflect the description
48 - don't send ids on requests, don't send password in response(!)
49 - put path parameters at the path level
50 - provide id for updating the pet in the path instead of body
51 - put partial pet update in body instead of query
52 - get /pets
53 - kill category and tag objects
54 - add auth as described
55 - use plural path segments
56 - don't return 405
58 - don't use GET for login(!)

swagger-api / swagger-petstore

API improvements meta issue #57

46 - remove unused models

47 - make query parameter format reflect the description

48 - don't send `id`s on requests, don't send `password` in response(!)

49 - put path parameters at the path level

50 - provide id for updating the pet in the path instead of body

51 - put partial pet update in body instead of query

52 - get /pets

53 - kill category and tag objects

54 - add auth as described

55 - use plural path segments

56 - don't return 405

58 - don't use GET for login(!)