Document access control

[LeonLiuY]

Hi,

Is there any way to make swagger API return the access control information?

For example, I use Apache Shiro with Spring MVC:

@RequiresRoles("admin")
@RequestMapping(value = "/{name}", method = RequestMethod.GET)
public Greeting greeting(@PathVariable String name) {
    return new Greeting(counter.incrementAndGet(),
            String.format(template, name));
}

I want to make the @RequiresRoles("admin") info available on swagger-ui.

Is there any easy way to config it?

[webron]

Is this an internal user role or an oauth2 scope?

On 9 October 2014 06:44, liuyang1204 notifications@github.com wrote:

Hi,

Is there any way to make swagger API return the access control information?

For example, I use Apache Shiro with Spring MVC:

@RequiresRoles("admin")@RequestMapping(value = "/{name}", method = RequestMethod.GET)public Greeting greeting(@PathVariable String name) {
return new Greeting(counter.incrementAndGet(),
String.format(template, name));}

I want to make the @RequiresRoles("admin") info available on swagger-ui.

Is there any easy way to config it?

—
Reply to this email directly or view it on GitHub
#719.

[LeonLiuY]

This is an internal user role with database realm.

Is this an internal user role or an oauth2 scope?

However, does this really matter?
The requirement is only to transform Shiro annotations to json format, then let swagger API add this json when it returns.

Purpose is to show access control information on swagger-ui, so developers can easily know how to use the APIs under different account types.

[webron]

It does matter, yes. The spec doesn't have room to carry that information unless it's part of the standard authorization schemes that are supported by Swagger.

One possibility you have is to apply a SwaggerFilter that will filter out the operations based the user authentication. So that if they don't have the "admin" role, they won't see that operation (though honestly, I'm not sure SwaggerFilter has access to that).

Another option is to add that information to the operation's "notes" field. However, since you use Spring MVC and I assume swagger-springmcv, you'd have to ask on their repository if you can extend their reader to include such information.

[LeonLiuY]

Thanks, webron!

I got some paths to solve this problem from your response.

I think the first way is a good idea, one account is only aware of what it can do. I guess we can already do this easily, according to my Google search.

The first way is useful for API users, it shows "what I can do".
But it is not enough for API developers. Developers want to know "Who can do what".

I feel "access control information" has great potential to be included in the swagger specification in the future.

[webron]

You're more than welcome to submit a specification feature request over at https://github.com/wordnik/swagger-spec so we could consider it for a future version. If you do that, please try to give an elaborate example with use cases and such. We need to see extensive definitions and also additional user requests for that feature for it to actually be accepted, but we always welcome new ideas.

[fehguy]

as @webron said, please open any spec suggestions in (now) swagger-spec