OAuth2 and Swagger Auth

[sunnyrjuneja]

Hi Swagger Team,

Greetings from the Ruby community. I was recently using Grape (API library), Rails, and Swagger and ran into an issue. It appears that Swagger-UI correctly sets an authorization header when added in the interface (api key field). However, if the endpoint has the option "authorizations" set with "oauth2", it will override the value.

I was able to create a test case in grape-swagger-rails ruby-grape/grape-swagger-rails#25 (comment).

To get a better understanding of how we tracked this down, checkout: ruby-grape/grape-swagger-rails#13. Specifically, this comment is helpful: ruby-grape/grape-swagger-rails#13 (comment).

[sunnyrjuneja]

Of course, if there's anything I can do to help triage this issue or make it more clear, please let me know.

[sunnyrjuneja]

I realize that it might be useful to have a JSON response to test this against... so here's the output of my repo to reproduce the problem (found at https://github.com/whatasunnyday/gsr-api-key).

{
  "apiVersion": "0.1",
    "swaggerVersion": "1.2",
    "produces": [
      "application/json"
      ],
    "apis": [
    {
      "path": "/hello.{format}",
      "description": "Operations about hellos"
    },
    {
      "path": "/swagger_doc.{format}",
      "description": "Operations about swagger_docs"
    }
  ],
    "info": {}
}

{
  "apiVersion": "0.1",
    "swaggerVersion": "1.2",
    "resourcePath": "/hello",
    "produces": [
      "application/json"
      ],
    "apis": [
    {
      "path": "/hello",
      "operations": [
      {
        "notes": "",
        "summary": "",
        "nickname": "GET-hello",
        "method": "GET",
        "parameters": [],
        "type": "void",
        "authorizations": {
          "oauth2": []
        }
      }
      ]
    }
  ],
    "basePath": "http://localhost:3000/api"
}

When "authorizations": { "oauth2": [] } is present, adding the api key and entering explore doesn't send the authorization in the headers :(.

[sunnyrjuneja]

Hey everyone, sorry to post again on this issue. I was wondering if there's anymore information I can provide to help get this issue resolved. I don't write a lot of js but I would love to put in a hand if someone can help me get started.

[IvanGoncharov]

@whatasunnyday "authorizations": { "oauth2": [] } is incorrect.
Read this.

swagger-js doesn't validate specs but you can use swagger-tools for that.
It have CLI, so you can use:
swagger-tools validate <resourceListingOrSwaggerDoc> [apiDeclarations...]
If you will have additional questions about Swagger format it better to post it here:
https://groups.google.com/forum/#!forum/swagger-swaggersocket

[sunnyrjuneja]

@IvanGoncharov That's very helpful. Thanks. I'll close this issue.

[sunnyrjuneja]

hey @IvanGoncharov i don't mean to bother but i noticed something in the test cases: https://github.com/swagger-api/swagger-js/blob/master/test/spec/v1/pet#L178-L185

          "authorizations": {
            "oauth2": [
              {
                "scope": "test:anything",
                "description": "anything"
              }
            ]
          },

Isn't this the same form of "authorizations": { "oauth2": [] }?

[fehguy]

hi @whatasunnyday sorry for the delay in responding! Yes, in the above example, there are scopes defined in the oauth2 definition. If the array is empty (but still present) then no scopes are required for the operation.

[sunnyrjuneja]

so @fehguy is "authorizations": { "oauth2": [] } valid syntax? if so, should this issue be reopened?

[antek-drzewiecki]

Sorry to meddle, but I got referenced to this issue.
authorizations": { "oauth2": [] } seems not an valid syntax. But authorizations": { "oauth2": {} } does.
oauth2 should be treated as an Hash / Dictionary / Set .
authorizations": { "oauth2": [] } is a valid in the API Description section.
authorizations": { "oauth": {} } should be used in the resource listing section.

[IvanGoncharov]

@whatasunnyday I meant that you missing top level authorizations.
Your authorizations inside method is perfectly fine, but you referencing not declared authorization:

The name given to the {Authorization Name} MUST be a friendly name that was given to an authorization scheme in the Resource Listing's authorizations.

As for this example:
https://github.com/swagger-api/swagger-js/blob/master/test/spec/v1/pet#L178-L185
Authorization scheme defined here:
https://github.com/swagger-api/swagger-js/blob/master/test/spec/v1/api-docs.json#L25

I still highly recommend you to use validator, it will save you a lot of time.
For example it have explicit check for exactly same mistake.

[sunnyrjuneja]

@IvanGoncharov Ah, thank you so much. That is very helpful.

[antek-drzewiecki]

Yeah @IvanGoncharov , thats what we also figured out. I was asuming @whatasunnyday was refering to the top level authorizations description in the issue he opened at my gem. 👍