feathersjs-ecosystem / feathers-swagger

Add documentation to your FeatherJS services and feed them to Swagger UI.
MIT License
225 stars 62 forks source link

How to restrict a specific method of a service being listed in API documentation? #177

Closed gauravbhusare closed 4 years ago

gauravbhusare commented 4 years ago

I am creating API documentation using feathers-swagger. I have setup all the things. I have one service named users which is authenticated service, but I do not want to show its remove method in my API documentation.

I tried using ignore in service swagger configuration as follows,

{
    description:Handles all user related operations,
    ignore:{
        tags: ["remove"] 
    },
   definitions:{
       //all the definitions
    }
}

but I am not getting expected output, all my methods are getting listed.

Help me achieving my expected results.

Mairu commented 4 years ago

If you want a method not to be in the swagger definition you have to define it as false.

service.docs = {
  operations: {
   find: false,
  }
}
gauravbhusare commented 4 years ago

@Mairu thanks for help. can you help me with one more point that if I write my custom service of users like users/xyz, how can I allow him for authentication. in the operations I tried

  {
       xyz:{
           find::
               security:[ { jwt:[] } ]
          }
      }
  }

and many other ways. and I did not found any documentation for such case.

Mairu commented 4 years ago

How to add another authentication method you can see in the security example.

https://github.com/feathersjs-ecosystem/feathers-swagger/blob/master/example/openapi-v3/security.js#L50

Don't forget that every authentication method has to be defined in the securitySchemes.

And here is an example with custom pathing / methods https://github.com/feathersjs-ecosystem/feathers-swagger/blob/master/example/openapi-v3/customMethods.js.

I hope this helps, if not you have to be more precise.

gauravbhusare commented 4 years ago
    module.exports = function (app) {
        const Model = createModel(app);
        const options = {
            Model,
            multi: true,
            whitelist: ['$elemMatch', '$populate']
        };

        app.use('/users/default', new SetDefaultUser());
        app.service('/users/default').hooks({
                           before: {
                patch: [authenticate('jwt']
            }
        });

        const users = createService(options);
        users.docs = usersSwagger(Model);

        app.use('/users', users);
        const service = app.service('users');
        service.hooks(hooks);
    };

Above is my service code where I have added one more service users/default. This service is available in API documentation. How can I provide authentication to this?

Mairu commented 4 years ago

You have 2 services, you have to configure the docs object for both of them.

module.exports = function (app) {
    const Model = createModel(app);
    const options = {
        Model,
        multi: true,
        whitelist: ['$elemMatch', '$populate']
    };

    const setDefaultService = new SetDefaultUser();
        // could also directly be set in the service class
    setDefaultService.docs = {
        operations: {
            patch: {
                security: [
                    { jwt: [] }
                ]
            }
        }
    };

    app.service('/users/default').hooks({
        before: {
            patch: [authenticate('jwt']
        }
    });

    const users = createService(options);
    users.docs = usersSwagger(Model);

    app.use('/users', users);
    const service = app.service('users');
    service.hooks(hooks);
};
gauravbhusare commented 4 years ago

@Mairu thank you so much for all your help.

ericuldall commented 4 years ago

Dropping certain methods doesn't seem to be working for me:

  const service = new Service(options, app);
  service.docs = {
    description: 'Some custom service',
    operations: {
      create: false
    }
  };

Service was generated with feathers cli.

Mairu commented 4 years ago

All I can say is, it should work and does work for me. (With feathers-swagger >= 1.0) The context you provided is not too much.

ericuldall commented 4 years ago

I'm using a feathers app generated with the cli. Then installed the most recent version of feathers-swagger. I've tried dropping the method on custom services created with the cli.

I actually wasn't using the other methods anyway and removing them from the class did the trick, so it's not an issue for now, but there may be some undocumented feature there.

Mairu commented 4 years ago

To clarify setting the a operation to false just removed the method from the generated swagger specification. It will still be available and can be used, it is just not documented.

ericuldall commented 4 years ago

Yes, my only intention was to make sure that method didn't show up as a line item in swagger UI and it's not working as expected. Again, just removing the default method definition in the class works for now since i'm not using the unwanted methods. If I find some time I'll try to create a repro.