Added note for working with virtual directories

[rschiefer]

I spent a day or more researching this so that I could use Swagger-UI in my ASP.NET Core API which is used with a reverse-proxy and virtual directory. In the end found Swagger-UI requires relative URLs to start with a period. Related to swagger-api/swagger-ui#4107

Hoping this documentation note will help others.

When creating a new PR, please do the following and delete this template text:

• Reference the issue number if there is one:

  Fixes #Issue_Number

  The "Fixes #nnn" syntax in the PR description causes
  GitHub to automatically close the issue when this PR is merged.

[guardrex]

Let's discuss this for a sec ...

We shouldn't say "virtual directory" because that's overloaded for IIS's vdir scenario, which isn't supported. Also, can it be shortened? ... Can the TIP just say ...

> [!TIP]
> If the Swagger assets are in a sub-directory, set the Swagger endpoint to a relative path using the ./ prefix (for example, ./swagger/v1/swagger.json).

Follow-up question: Will it also resolve the path correctly in this scenario if provided like this: swagger/v1/swagger.json?

[rschiefer]

@guardrex Yeah I went back and forth on how to described this. The Swagger-UI project says any relative path should use './'.

In my particular case and the linked swagger-ui issue above, its more complicated than just a subdirectory. This is specifically needed for virtual directory type of scenario where either IIS or a reverse proxy is routing a URL with sub-paths to your ASP.NET app. Where the ASP.NET app should consider the subpath as its root. Sorry if I'm not describing this well.

[guardrex]

My only main concern is the use of the term "virtual directory," since we're been trying to educate devs not to use that IIS scenario with ASP.NET Core apps.

When it comes to Swagger, I defer to @scottaddie, who really knows his stuff in this area. Whatever you cats work out, I just recommend being careful with the terms "virtual directory" and "IIS" in close proximity. If the scenario can be described with "sub-directory", "virtual path," "relative path," or something along those lines, it will be better than referring to "virtual directory."

[EDIT] One can add a web.config in a sub-app to remove the handler, but it's confusing to offer workarounds.

[rschiefer]

That makes sense. I can simulate the virtual path issue by setting the following in the launchsettings file under iisSettings.

  "applicationUrl": "http://localhost:56943/Service/v0.0.8/",

[Rick-Anderson]

@scottaddie please review

[scottaddie]

@rschiefer Thank you for your patience and contribution. Your changes will go live within the next 24 hours.

[rschiefer]

Awesome, thanks!