Server URI is parsed incorrectly when the URI is relative

[selman92]

When parsing this document with OpenAPI.NET, it parses the server URL as: http:///v2, while it should only parse /v2 and not append http:// to it.

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about Swagger at <a href=\"http://swagger.io\">http://swagger.io</a> or on irc.freenode.net, #swagger.  For this sample, you can use the api key \"special-key\" to test the authorization filters"
  version: 1.0.0
  title: Swagger Petstore YAML
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "[email protected]"
  license:
    name: Apache 2.0
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
basePath: /v2
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: "http://swagger.io"
  - name: store
    description: Operations about user
  - name: user
    description: Access to Petstore orders
    externalDocs:
      description: Find out more about our store
      url: "http://swagger.io"
schemes:
  - http

[PerthCharern]

Thanks for reporting @selman92.

V2 spec splits out the URL into multiple parts, including basePath, host and schemes. In V3, these are all combined into the Server Object url.

Since our model is based on V3, when we read V2 document, we need to reconstruct the URL based on the given info. In your case, we use the http in schemes and the /v2 in basePath to construct the URL http:///v2. This V3-based DOM now conveys the same meaning as your original V2 doc.

Note that the host in the URL is empty. Ideally, we should be able to populate the host with "the host serving the documentation" but we do not have that information. We'll probably need to include an option for the caller to supply that information.

[selman92]

I understand that the host information is not available. However, in our code base we already have an absolute URI to use as base URI in case the swagger documentation provides a relative URI. So that is why I expected server.Url property to return the relative URI. Although I have solved this issue by using OpenApiSettings and providing the base URI, it would be nice if the server.Url returned relative URI instead of http:///v2 which looks kinda weird :)

[PerthCharern]

That's true. From a practical standpoint, I agree it makes more sense to just output /v2 as a relative URL. For this case specifically, if you remove the scheme: -http part, I think you will get the desired output. Would that work in your case, or do you need to specify HTTP?

Longer discussion:

I think we are in a weird technical situation. We are given the information that the scheme is 'http'. If we were to only add /v2 to the DOM, we would be dropping information which could have been retained. If we keep the http, then we run into a weird http:////v2, which is not a valid URL.

Your V2 document is saying "Use the default host, with relative path /v2, and force the scheme to be http". From my reading of the V2 and V3 specs, this is actually something that I think V3 doesn't support. I can't specify a scheme unless I also explicitly specify a host since it's now just one URL property.

Since there's no way to represent this is V3, it seems like dropping the information on scheme when host is not present (i.e. outputting just /v2) might be the right thing to do.

@darrelmiller Does this align with your understanding of this V2/V3 URL differences?

[PerthCharern]

I would also further argue that there might not be much of a use case to specify scheme if the default host is to be used. I don't think the server should serve the documentation and the API under a different protocol (http/https). A somewhat related article: https://www.paulirish.com/2010/the-protocol-relative-url/

Let me think about this a bit more.