Support for external HTTP references needing authentication

[camball]

I'm not expert on proxies, but I'm having trouble getting validation to work when pulling in externally-defined HTTP references. I get an error like:

Error reading file "https://github.mycompany.com/.../component.yaml: cannot open openapi-internal-https://github.mycompany.com/.../component.yaml. Detail: Response code 401 (Unauthorized)"

I added github.mycompany.com to my openapi.approvedHostnames:

"openapi.approvedHostnames": [
    "github.mycompany.com"
]

and the 401 is where I'm stuck with. I'm wondering if it's a proxy issue, or otherwise, and if there's a solution at all here. Thanks!

[ak1394]

Hi @camball !

We've recently added some support for authentication for external references, the details in the README file in "Configure authentication for external references in OpenAPI files" section.

Do you know the necessary authentication details required to retrieve files from "https://github.mycompany.com/" ?

[camball]

Thanks—that worked great! I followed these GitHub authentication instructions for my use-case. Didn't realise that settings pane existed, lol.

Now that I have that working, I now get another error which I believe is unrelated, Failed to resolve $ref. I didn't mention before, but the full URL structure I am pulling in looks like:

// does not work

parameters:
- $ref: 'https://github.mycompany.com/api/v3/repos/.../parameters.yaml#/MyParameter'

where it uses JSON Pointer notation to reference just the key MyParameter. When I take away the pointer notation, the error goes away and the reference is resolved just fine:

// works

parameters:
- $ref: 'https://github.mycompany.com/api/v3/repos/.../parameters.yaml'

This I think may be an issue with the extension, but am not sure. I know the extension supports JSON Pointers, but am wondering if there is an issue with it being as part of an external URL. I also validated that MyParameter is a valid key in the referenced YAML. Lastly, I couldn't find any relevant logs in any of the output panes I checked.

[ak1394]

Could you provide a snippet from, or a whole parameters.yaml?

[camball]

Sure, here's the full content of parameters.yaml, with some replaced values, nearly identical to the actual:

Authorization:
  name: Authorization
  in: header
  required: true
  description: My Authorization description
  schema:
    type: string
    example: an example here
an-id:
  name: an-id
  in: header
  description: My ID description
  required: true
  schema:
    type: string

and the links look like

https://github.mycompany.com/api/v3/repos/.../parameters.yaml#/Authorization
https://github.mycompany.com/api/v3/repos/.../parameters.yaml#/an-id

[ak1394]

Thanks for the info. I would expect this to work, but let me setup something similar here to make sure we don't have an bug or regression.

[ak1394]

It should be working, tested using simple OpenAPI file + your parameters.yaml.

There could be some issues handling nested references (i.e. referencing a file that in turn has refs), but the one below should be ok.

info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /test:
    get:
      parameters:
        - $ref: http://<hosname>/parameters.yaml#/Authorization
        - $ref: http://<hosname>/parameters.yaml#/an-id
      responses:
        '200':
          description: OK