Add support for deprecated flag

[bmpickford]

Swagger supports the deprecated flag on paths, see https://swagger.io/docs/specification/paths-and-operations/. Would be good to be able to have this carry over in the AWS documentation.

This would look something like:

createItem:
  handler: handler.create
  events:
    - http:
        path: create
        method: post
        documentation:
          summary: "Create something"
          description: "Creates the thing you need"
          deprecated: true,
          tags:
            - "Data Creation"
            - "Some other tag"