********************************************************************
build api descriptor object to be used by static docs plugins

@returns {object} the descriptor for the api
function() {
    var self = this

    return {
      version: '1.0.0', // XXX ?
      title: self._service.serviceName || 'Service',

      description: self._service.description,
      longDescription: null,

      // headers, query, path, body
      parameters: self._generateParameterDescriptors(self._service.parameters),

      // XXX: not implemented
      securityModel: null,

      // XXX: should probably pull these from the service
      schemes: ['http'],
      consumes: ['application/json'],
      produces: ['application/json'],

      // this should be a flattened list of endpoints
      endpoints : self._generateEndpointDescriptors()
    }
  }