Add documantation for customization of path object

[silberjan]

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

[silberjan]

Oh thats exactly what i need. Thanks @arddor !

Documentation for that feature would be really helpful ;)

[daffl]

If someone would like to add the documentation (just a quick example or paragraph with an explanation) feel free to edit the README. It'll then just become part of the main docs with the official release.

[akshay2604]

If someone can post a basic documentation for this, it will be really helpful.

I am currently doing this.

  const doc = {
    path: {
      '/api/xbcBusinesses': { // <--- not sure about this
         description: 'A service for business',
         find: {
            parameters: [{
            description: 'Get examples by name',
            in : 'query',
            required: false,
            name: 'email',
            type: 'string'
         }],
         },
          create: { 
            description: 'Custom POST description',
            responses: {
              '201': {
                description: 'New Business was created'
              }
            }
          }
      }
    }
  }

and register it here.

app.use('/api/xbcBusinesses',Object.assign(service(options), {
      docs: doc
}));

This is the response i am getting.

Obviously I am not able to get the doc here.

Also I am not able to get the swagger.definition part from above. Where is swagger defined?

[josx]

My example using mongoose :

  const doc = {
     find: {
       parameters: [{
         description: 'Search model by string',
         in: 'query',
         required: false,
         name: '$text[$search]',
         type: 'string'
       }],
     },
     get: {
       parameters: [{
         description: 'Search mode by id',
         in: 'path',
         required: true,
         name: '_id',
         type: 'string'
       }],
     }
   };

[Mairu]

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