API improvements meta issue

[nrktkt]

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

• Remove unused sections #46 - remove unused models
• Correct filter params #47 - make query parameter format reflect the description
• Use readOnly and writeOnly on models #48 - don't send ids on requests, don't send password in response(!)
• Spec path parameters at path level #49 - put path parameters at the path level
• Update pet at the path for that specific pet #50 - provide id for updating the pet in the path instead of body
• updatePetWithForm using patch #51 - put partial pet update in body instead of query
• Combine findPetsBy(Status/Tag) into general GET /pets #52 - get /pets
• Replace category and tag objects with simple string #53 - kill category and tag objects
• Add auth to user routes #54 - add auth as described
• Use plural resources in path where applicable #55 - use plural path segments
• Return 400 instead of 405 for invalid input #56 - don't return 405
• Don't use GET for log in or out #58 - don't use GET for login(!)

[CobaltCause]

@tim-lai, @char0n, @frantuma: sorry for pinging all of you (the three most recent committers to master as of writing), but is there any chance of any these PRs getting looked at? Some of them might be breaking changes to the API and need server work, but some of them fix issues local to the spec such as #46 and #56.