How to define role/permission security in Swagger?

In my API documentation, I would like to define the security necessary for each API endpoint. The project has defined roles and permissions that determine which users can access the APIs. What is the best way in Swagger to document this information? Is there a best practice or recommendation on how to show this detail?

This what I tried out using securityDefinitions and a self-defined variable for the roles, but that information (x-role-names) didn’t get copied over into the documentation when I ran it through swagger2markup or using swagger-ui.

    "securityDefinitions": {
    "baseUserSecurity": {
          "type": "basic",
          "x-role-names": "test"
       }
    }

What’s the best way to document the role and permission information per endpoint?

[atdiff]

@fehguy After looking over the specs, I’m still not sure how to accomplish the ability to display the user roles/permissions required for an API and have that info appear in the resulting Swagger documentation. My ideal is for each path could indicate the user role and permissions required to access it. Basically something very roughly along the lines of “api/someCall” roles: [“admin”,“specialist”] and permissions: [“view_screen”, “edit_screen”].

There are 2 avenues I’ve tried at the moment:

• Description field. Just listing the roles in the description field (not ideal and in some markup only gets displayed at the security section in the bottom)

"securityDefinitions": {
        "baseUserSecurity": {
          "type": "basic",
          "description": "Roles required: Admin, Specialist",
        }
    },

Description rendered:

• Scope. Providing a scope for the security object. It’s not allowed in the spec and throws an error in the editor, but swagger2markup still allows and parses it. "security": [{"baseUserSecurity": ["Admin", "MarketSpecialist"]}],

Scope rendered:

Scope seems to fit better to some degree, but it goes against the spec which doesn’t seem like a good idea overall. So I’m not sure how this would best be documented.

[akongnwi02]

Hi. How did you go about this issue?