Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Authorization (lock symbol) is rendered incorrectly #4402

Open
m-mohr opened this issue Apr 3, 2018 · 7 comments
Open

Authorization (lock symbol) is rendered incorrectly #4402

m-mohr opened this issue Apr 3, 2018 · 7 comments

Comments

@m-mohr
Copy link

@m-mohr m-mohr commented Apr 3, 2018

I have endpoints that either have a required authorization or an optional authorization (see example).
I think the lock symbols are rendered incorrectly. It shows a black locked symbol for optional authorization (/public) and and a gray unlocked symbol for required authorization (/private).

Q A
Bug or feature request? Bug
Which Swagger/OpenAPI version? 3.0.0 and 2.0
Which Swagger-UI version? 3.x currently used by hosted Swagger Editor + master branch (03.04.2018 15:36)
How did you install Swagger-UI? Hosted Swagger Editor + locally using master branch (03.04.2018 15:36)
Which browser & version? Chrome 65.0.3325.181
Which operating system? Windows 10

Demonstration API definition

openapi: 3.0.0
servers:
  - url: 'https://localhost/api/'
info:
  title: OpenEO API
  version: 0.3.0
paths:
  /public:
    get:
      summary: This endpoint allows users to access it with AND without authentication.
      security:
        - {}
        - Bearer: []
      responses:
        '200':
          description: ...
  /private:
    get:
      summary: This endpoint allows users to access it only with authentication.
      security:
        - Bearer: []
      responses:
        '200':
          description: ...
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Expected Behavior

It shows a gray unlocked symbol for optional authorization (/public) and and a black locked symbol for required authorization (/private).

Current Behavior

It shows a black locked symbol for optional authorization (/public) and and a gray unlocked symbol for required authorization (/private).

@webron

This comment has been minimized.

Copy link
Member

@webron webron commented Apr 3, 2018

I understand the confusion, but it's actually working as expected.

When a user fills the authorization, the lock becomes closed and black - that indicates that there's security information provided. An unlocked lock, means that the user has not provided the information. We've had discussions in the past about how some people expect it to be one way and some the other. We'll consider changing it altogether to make it clearer.

In your case, it behaves as expected (in our intent) - since you allow a no-security option, meaning the user can use the call without providing credentials, the lock is black and locked indicating you can execute the call.

@IceflowRE

This comment has been minimized.

Copy link

@IceflowRE IceflowRE commented Sep 25, 2018

Thats more than confusing.

First a better example:

openapi: 3.0.0
servers:
  - url: 'https://localhost/api/'
info:
  title: OpenEO API
  version: 0.3.0
paths:
  /public:
    get:
      summary: This endpoint allows users to access it only without authentication.
      responses:
        '200':
          description: ...
  /misc:
    get:
      summary: This endpoint allows users to access it with AND without authentication.
      security:
        - {}
        - Bearer: []
      responses:
        '200':
          description: ...
  /private:
    get:
      summary: This endpoint allows users to access it only with authentication.
      security:
        - Bearer: []
      responses:
        '200':
          description: ...
  
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Three states exist and the natural interpretation of those is easy:

state interpretation
none No authentication required.
open Optional authenticaton, thats why its already open, because you can access it even without.
locked You need an authorization to open it and only with you can access it.

To signalize provided security information, mark the corresponding locks green or so.

@bmbell

This comment has been minimized.

Copy link

@bmbell bmbell commented Jan 16, 2019

I found the current implementation very confusing. Just take a real-life scenario - if something is locked (in this case, the black lock symbol), then it generally means it cannot be accessed without a key (e.g. an api key). The key "unlocks" the service, and grants access to it. Thus, the open lock symbol would be shown after credentials were entered.

@RolandoAvila

This comment has been minimized.

Copy link

@RolandoAvila RolandoAvila commented Feb 7, 2019

Can someone provide the explanation that clarifies how this is not confusing? I would like to know how to explain it to the consumers to my APIs.

@shockey

This comment has been minimized.

Copy link
Member

@shockey shockey commented Feb 7, 2019

@RolandoAvila, @webron summed it up above pretty well IMO.

@RolandoAvila

This comment has been minimized.

Copy link

@RolandoAvila RolandoAvila commented Feb 8, 2019

Thanks @shockey , yes I read his comment, but I guess it's not convincing me that is an intuitive solution. If it was, I shouldn't have to continuously explain this to those new to swagger's documentation (which I love working with btw). I even surveyed some random non-technical people and sure enough all had the same confused conclusion I had.

@MikeGriffinReborn

This comment has been minimized.

Copy link

@MikeGriffinReborn MikeGriffinReborn commented Oct 24, 2019

Very poor design. The API is locked until I authenticate then it is unlocked to me. I suggest you guys change this. It's beyond wondering how the thinking behind the current logic came about? Makes zero sense the way you have it now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
7 participants
You can’t perform that action at this time.