Add documantation for customization of path object

Currently, I see no way of editing the path object inside the servcie. Only the definitions get parsed.

It would be great to add some information to the path object e.g. to set possible responses.

it could look something like this:

class MessagesService {

  constructor(options) {
    this.options = options || {};

    this.docs = {
      description: 'A service to send messages',
      definitions: {
        messages: { (...) }
      }
      path: {
        messages: {
          create: {   // Anything inside would override the default config for "/messages".post
            description: 'Custom POST description',
            responses: {
              '201': {
                description: 'New Message was created'
              }
            }
          }
        }
      }
    }
  }

  (...)
}

[arddor]

This is something which I also discovered recently while looking closer at the sequelize example:

const doc = {
  description: 'Operations about Users.',
  definitions: {
    'UserPaginate': swagger.definition({
      attributes: {
        data: Sequelize.ARRAY('users')
      }
    }, {
      extends: ['paginate']
    })
  },
  definition: swagger.definition(model),
  securities: ['find'],
  find: {
    parameters: [{
      description: 'Get examples by name',
      in : 'query',
      required: false,
      name: 'email',
      type: 'string'
    }],
    responses: {
      '200': {
        description: 'successful operation',
        schema: {
          '$ref': '#/definitions/UserPaginate'
        }
      }
    }
  }
};

As you see you can define response with find, get, … I would say that there should be some more documentation to make that clear

[Mairu]

This is all configurable by now. Documentation and examples were added with version 1.0.0.