Support Relative URL definition

[JustinGrote]

Tried building https://www.paessler.com/support/prtg/api/v2/oas/prtg.api.yaml and got error generating the client: Invalid URI: The format of the URI could not be determined. This is probably because the server URLs are relative as it is an on prem product, support this scenario which is supported in openapi and allow supplying the server at runtime or via middleware.

[baywet]

Hi @justienGrote,
Thanks for your interest in kiota and for reporting this.
For context I'm guessing your OpenAPI description looks something like this.

openapi: 3.0.1
info:
  title: OData Service for namespace microsoft.graph
  description: This OData service is located at https://graph.microsoft.com/v1.0
  version: 1.0.1
  x-ms-generated-by:
    toolName: Microsoft.OpenApi.OData
    toolVersion: 1.0.9.0
servers:
  - url: /foo/api

The parsing of the server URL is located here

kiota/src/Kiota.Builder/KiotaBuilder.cs

Line 248 in 579736a

config.ApiRootUrl = openApiDocument?.Servers.FirstOrDefault()?.Url.TrimEnd('/');

It's also being parsed here, but I don't believe this is what's currently failing your generation.

kiota/src/Kiota.Builder/Validation/NoServerEntry.cs

Line 11 in 579736a

if (!document.Servers.Any() || string.IsNullOrEmpty(document.Servers.First().Url?.TrimEnd('/')))

And lastly, a unit test for it could be added as a new test like this one.

kiota/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs

Line 99 in 579736a

public async Task ParsesKiotaExtension()

With that information would you like to submit a pull request to address this issue?

[baywet]

I've been giving a second look at this. While with this description and the current kiota logic the generated server URL would be wrong, this is not what's causing kiota to crash. If that were the only issue, kiota would generate succesfully but the client would be unable to call the API because of a wrong api url that could be changed at runtime.

This description makes use of external references ($ref: doc.yaml#/components/schema/foo) which kiota never supported to begin with and we never revisited that aspect historically.
Here are a couple of things that need to happen for external references to be properly supported:

• the base URL of the document and load external references need to be set with the OpenAPI library.
• the effective schema need to be obtained all along the process while resolving external references.
• naming needs to account for the new reference format.

In addition to this, I found a bug in the OpenAPI library which I've submitted a pull request to address.
microsoft/OpenAPI.NET#1159

[baywet]

After further internal discussions, we won't be implementing external references support in Kiota just yet. OpenAPI.net, the library we use to parse descriptions has plans to drastically improve the external references story with v2 and we'll rely on that once it becomes available.
You can use a tool like hidi to inline the references in the meantime.

Now, what's left is:

• fixing a bug in OpenAPI.net with relative links, that's the PR I linked in the previous comment and we'll update it in kiota as soon as it comes out.
• build the absolute base url from a relative server URL (the scope of this issue), for which I'll submit a PR, probably not the next week but the following one since we have internal events next week.

[JustinGrote]

Thanks, I made an attempt, and it mostly worked, however a lot of the references and classes didn't convert right with hidi. I'm going back to openapi-generator which does work with this spec, looking forward to what your team comes up with, the API I referenced above might be a good test case as it's fairly complex.

[baywet]

Keeping this open so we can track progress on relative server URL

[JustinGrote]

I missed the "just yet" part, I thought it was a wontfix. Thanks.

[JustinGrote]

@baywet thank you!

[baywet]

That should go out in our next release, early march