As a reader of the generated documentation, I want to see required scopes defined in the security key, so I know which ones my token needs for an operation to work

[leolabs]

User Story Description

Example spec:

paths:
  /search:
    get:
      summary: Search
      description: Search all available resources.
      operationId: search
      security:
        - bearerAuth:
          - users.list
          - apps.list
          - datasets.list
          - tags.list

Currently, the scopes defined here aren't shown in Elements:

It would be great to have them listed as part of the security section. A quick example of what this could look like:

Acceptance Criteria

• [ ] Security scopes that are defined in the spec should be shown in the security box of operations

Sprint Ready Checklist

• [ ] Acceptance criteria defined
• [ ] Team understands acceptance criteria
• [ ] Team has defined solution / steps to satisfy acceptance criteria
• [ ] Acceptance criteria is verifiable / testable
• [ ] External / 3rd Party dependencies identified

[mnaumanali94]

I believe this was fixed in https://github.com/stoplightio/elements/pull/1878

Are you using an older version of elements by any chance?

[Thomasdezeeuw]

Hey @mnaumanali94 we're using version 7.5.18 and this is how it looks for us:

Our spec is hosted here: https://www.slight.dev/api/reference/operations/search, the full yaml: https://www.slight.dev/http_spec.yaml. The relevant parts (I think) are the following:

paths:
  /apps:
    get:
      security:
        - bearerAuth: ["apps.list", "apps.read"]
        - PAT: ["apps.list", "apps.read"]
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    PAT:
      type: http
      description: Personal Access Token (PAT).
      scheme: bearer
      bearerFormat: PAT

If I understand the spec correctly this should set the scopes for the security scheme, but maybe Elements processes it differently?

[mnaumanali94]

@Thomasdezeeuw Scopes are used on Oauth schemes as defined here: https://spec.openapis.org/oas/v3.1.0#security-scheme-object

[defunctzombie]

@mnaumanali94 openapi 3.1 allows SecuritySchemes other than oauth to specify scopes. The request here is to surface these non-oauth security scopes in the UI.

I did some poking around the elements code to see if I could add this and I think the initial fixes need to happen in the http-spec repo: https://github.com/stoplightio/http-spec/issues/207

Until the parsing of the spec includes scopes for http and apikey security (now allowed in openapi 3.1), elements won't be able to display it in their UI.

[chohmann]

Hello!

Our team recently took over the stewardship of the elements repo.

Due the volume of un-triaged issues that are pretty old and the time it would take us to get caught up on all of them, we kindly ask that you open up a new ticket if this is still an issue you're struggling with.

If you open a new issue please include:

• clear steps to reproduce that include example OAS specs, application setup, code, etc.
• the error or issue you are experiencing
• the expected behavior

We will be triaging any new tickets in a timely manner.

Thank you for understanding!