[英]How do I change the Swagger default URL and use a custom one?
I have an API that I created in.NetCore 3.1 and have enabled Swagger(OAS3) using Swashbuckle.我有一个在.NetCore 3.1 中创建的 API,并使用 Swashbuckle 启用了 Swagger(OAS3)。 By default when my app starts if brings up the Swagger page using this URL:
默认情况下,当我的应用程序启动时,如果使用此 URL 调出 Swagger 页面:
http://{port}/swagger.index.html
I would like to customize the Swagger URL so that it includes the name of the application that is running.我想自定义 Swagger URL 以便它包含正在运行的应用程序的名称。 The reason I am doing this is because I am using path-based routing with Nginx running in AWS Fargate.
我这样做的原因是因为我在 AWS Fargate 中运行 Nginx 使用基于路径的路由。
I will have several API containers running in the Fargate task and Nginx will receive the REST requests coming from the Application Load Balancer and from the path (eg /api/app1), it will route the request to the correct container port for the target application.我将有几个 API 容器在 Fargate 任务中运行,并且 Nginx 将接收来自应用程序负载均衡器的 REST 请求,并从目标应用程序路径(例如 /api/app)路由到目标应用程序请求的正确端口 1 .
So, for example, I have three apps: App1 on port 5000, App2 on Port 5001 and App3 on port 5003.因此,例如,我有三个应用程序:端口 5000 上的 App1、端口 5001 上的 App2 和端口 5003 上的 App3。
If the user makes a request to https://api/app1 , Nginx will detect the path and forward the request to port 5000, which is App1's container port.如果用户向https://api/app1发出请求,Nginx 将检测路径并将请求转发到端口 5000,即 App1 的容器端口。
However, to make sure that the correct Swagger page comes up, I need to add "api/App1" to Swagger's URL so that Nginx will forward the request to the correct container.但是,为了确保出现正确的 Swagger 页面,我需要将“api/App1”添加到 Swagger 的 URL 以便 Nginx 将正确的请求转发到容器。 In this case, it's App1.
在这种情况下,它是 App1。
In other words, I want my Swagger URL to look like this:换句话说,我希望我的 Swagger URL 看起来像这样:
https://api/app1/swagger/index.html
What I've tried我试过的
In my Startup.cs file I have added the following:在我的 Startup.cs 文件中,我添加了以下内容:
// Define prefix for application
private readonly string baseApplicationRoute = "api/app1";
// Enable OAS3 JSON middleware
app.UseSwagger(c =>
{
c.RouteTemplate = baseApplicationRoute+"/{documentName}/swagger.json";
});
app.UseSwaggerUI(c =>
{
var endpoint = $"/{baseApplicationRoute}/{version.ToLower()}/swagger.json";
c.SwaggerEndpoint(endpoint, $"APP1 API - {version}");
c.RoutePrefix = string.Empty;
});
This compiles and works, however it is still using the same Swagger URL of:这可以编译和工作,但是它仍然使用相同的 Swagger URL :
http://{port}swagger.index.html
I think all this is doing is changing the location of the swagger.json because on the Swagger UI that comes up it is showing:我认为所有这一切都是在改变 swagger.json 的位置,因为在出现的 Swagger UI 上显示:
/api/app1/v1/swagger.json
My launchSettings.json file is specifying the "launchUrl" as "swagger".我的 launchSettings.json 文件将“launchUrl”指定为“swagger”。
I think I'm close, but I am obviously missing something.我想我已经接近了,但我显然错过了一些东西。 To recap I'm just trying to change:
回顾一下,我只是想改变:
The default Swagger URL默认 Swagger URL
http://{port}swagger.index.html
To my custom one here:给我这里的自定义一个:
http://{port}/api/app1/v1/swagger.index.html
That way Nginx can detect "/api/app1" and route to the correct container.这样 Nginx 可以检测到“/api/app1”并路由到正确的容器。
What am i missing?我错过了什么?
I found the solution to this issue:我找到了解决这个问题的方法:
In the Configure section of Startup.cs I did the following:在Startup.cs的配置部分中,我执行了以下操作:
First I added the folowing variable:首先,我添加了以下变量:
private readonly string swaggerBasePath = "api/app";
Next I configured the path using UseSwagger and UseSwaggerUI to use the swaggerBasePath variable:接下来,我使用UseSwagger和UseSwaggerUI配置路径以使用swaggerBasePath变量:
app.UseSwagger(c =>
{
c.RouteTemplate = swaggerBasePath+"/swagger/{documentName}/swagger.json";
});
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint($"/{swaggerBasePath}/swagger/v1/swagger.json", $"APP API - {version}");
c.RoutePrefix = $"{swaggerBasePath}/swagger";
});
Finally, I modified launchSettings.json to point to the new base path:最后,我修改了 launchSettings.json以指向新的基本路径:
"launchUrl": "api/app/swagger",
Then is was able to hit the Swagger page using:然后能够使用以下命令访问 Swagger 页面:
https://localhost/api/app/swagger/index.html
I testing this with Nginx and it was able to route to the correct container.我用 Nginx 对此进行了测试,它能够路由到正确的容器。
I can easily tweak the base path (for instance to add the API version number) by simply modifying the swaggerBasePath variable and tweaking the launchSettings.json file to match the value of the variable.通过简单地修改swaggerBasePath变量并调整launchSettings.json文件以匹配变量的值,我可以轻松地调整基本路径(例如添加 API 版本号)。
Hopefully, this will help someone in the future.希望这将有助于将来的某人。
(I am using.Net 6) (我正在使用.Net 6)
I needed this because I was facing issue in api gateway.我需要这个,因为我在 api 网关中遇到问题。 So, What I did, I left my launch settings as it is.
所以,我所做的,我保留了我的启动设置。
launchsettings启动设置
"launchUrl": "studentservice/api/swagger",
I made these two changes in my Startup.cs
file.我在我的
Startup.cs
文件中进行了这两项更改。
Note: Your launchsettings url and routeprefix url should match.注意:您的启动设置 url 和路由前缀 url 应该匹配。
ConfigureService Method
, I have added SwaggerDocConfigureService Method
中,我添加了 SwaggerDocservices.AddSwaggerGen(c =>
{
c.SwaggerDoc("student", new OpenApiInfo { Title = "Student Service Api", Version = "1.0" });
}
Configure Method
, I have added SwaggerDocConfigure Method
中,我添加了 SwaggerDoc app.UseSwagger();
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.)
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/student/swagger.json", "Student Services Api");
c.RoutePrefix = "studentservice/api/swagger";
});
}
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.