search

RicoSuter / NSwag

The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.
http://NSwag.org
MIT License
6.68k stars 1.24k forks source link

Question: How do I configure SwaggerUI3 for documents on another server? #3374

Open yvsean opened 3 years ago

yvsean commented 3 years ago

Apologies if this is more a question for swagger-ui, but it does seem the configuration interfaces I am working through are part of NSwag.

The TLDR of my situation is that, Because Reasons, the server hosting the Swagger UI is serving as a proxy relay to my actual APIs. I need Swagger UI to default to a document route on the actual API server, as well as in post-processing replace the API paths with that of the hosting proxy server. I've found myself struggling with both of these things, and I have not yet found the right illuminating documentation.

On the first part, there are quite a few variables involved (Path, MiddlewareBasePath, DocumentPath, routes, etc), but I haven't yet found documentation on how to utilize all of them. While the UI will work just fine if I don't use routes and allow browsing, and I then directly enter the path to the document on the API server, I haven't been able to get it to default to this. I've done some source-diving to see if I could reverse engineer a way, but I haven't been successful.

On the second part, it seems like it should be pretty straightforward, but what I've found is the PostProcess method that I set isn't getting called, even when I directly fetch the document as described above. I haven't yet been able to find an explanation for that behavior, either.

Has anyone happened to have done something like this before? Any recommendations?

maxschaf commented 3 years ago

I have the same issue. NSwag is used as build step and it generates the specification.json referring to all endpoints with url "/api" , This works on localhost but not in a subdirectory on IIS. A relative URL or basepath is needed and I can't figure out how to set this with nswag.json or in asp.net core startup.cs . Any idea? Further details see https://github.com/jasontaylordev/CleanArchitecture/issues/339

yvsean commented 3 years ago

I actually had eventually gotten this to work for me. I was using OWIN ASP.NET, though, because that's unfortunately what the public-facing machine currently is in. I don't know what implications that may have on setup, though the APIs didn't ultimately seem that different from Core.

For the first part, I'd ended up using ASP routing to set up a path to the location I wanted SwaggerUI to appear. I configured the UI with a Path of "/", a MiddlewarePath of null, and a SwaggerRoute of the document URL on the foreign server. The document route would get mangled, being prefixed with the ASP route path; I updated the SwaggerUI TransformToExternalPath method to handle and remove that, as a special case.

The second part, the lack of PostProcess calls, was actually because apparently the PostProcess method is only called when you invoke UseSwaggerUI3 with local controller types to render a document from, which we obviously don't have in this case. PostProcess is applied as part of OpenApiDocument.FromJsonAsync method, so I ended up having to set up an HTTP handler to intercept the document response, run the incoming JSON through that method to apply PostProcessing, and then return the modified JSON. It's kind of strange to me that this isn't done implicitly regardless the document source, but at least this hack did work.