ASP.NET Core 6.0 Web API 与 Swagger UI 部署到 IIS 的实践指南
2024-02-12 21:05:02
利用 Swagger UI 增强您的 ASP.NET Core Web API
部署到 IIS，交互式文档化唾手可得
前言
ASP.NET Core 已成为构建现代 Web 应用程序的热门选择。通过其灵活性和强大的特性，它赋予开发人员创建高性能、跨平台应用程序的能力。本文将深入探究将 ASP.NET Core Web API 与 Swagger UI 部署到 IIS 的过程。Swagger UI 提供了一个交互式界面，可以方便地探索和测试您的 API，从而提升其可维护性和可用性。
第 1 步：创建 ASP.NET Core Web API 项目
首先，打开 Visual Studio 并创建一个新的 ASP.NET Core Web API 项目。从“空”模板开始，为您的 API 命名。
第 2 步：集成 Swagger UI
要集成 Swagger UI，您需要安装 NuGet 包。在 Package Manager 控制台中，运行以下命令：
PM> Install-Package Swashbuckle.AspNetCore
接下来，在 Startup.cs 文件中添加以下代码以注册 Swagger 服务：
public void ConfigureServices(IServiceCollection services)
{
// ...
// Register the Swagger generator and expose it on /swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
// ...
}
第 3 步：部署到 IIS
现在，您已准备好将 Web API 部署到 IIS。编译您的项目并生成一个发布版本。将生成的发布文件复制到 IIS 服务器上的目录。
第 4 步：设置 Swagger UI 为主页
为了方便访问 Swagger UI，您需要将其设置为网站的主页。在 IIS 管理器中，右键单击您的网站并选择“管理网站”。在“主页”字段中，输入“swagger/index.html”。单击“应用”保存更改。
第 5 步：设置内网穿透（可选）
如果您的 API 位于内网，您需要设置内网穿透才能使其对外部用户可用。可以使用反向代理服务器（如 Nginx）、Microsoft Azure Application Gateway 或 VPN 连接来实现此目的。
第 6 步：验证部署
现在，您已成功部署 ASP.NET Core Web API 和 Swagger UI。在浏览器中输入您的 API URL，您应该会看到 Swagger UI 界面，其中包含交互式测试功能和 API 文档。
结论
通过将 Swagger UI 集成到您的 ASP.NET Core Web API 并部署到 IIS，您可以为您的 API 提供一个方便的交互式界面。这可以大大简化应用程序的测试和维护，同时提高其可访问性和可用性。
常见问题解答
-
Swagger UI 与 OpenAPI 有何关系？
Swagger UI 是一个用于查看和交互式测试 OpenAPI 规范的工具。OpenAPI 规范是一种 RESTful API 的标准格式，而 Swagger UI 提供了一种可视化表示。 -
如何为我的 API 生成 OpenAPI 规范？
如果您使用了 Swagger NuGet 包，OpenAPI 规范将自动生成并可在/swagger/v1/swagger.json路径下访问。 -
如何自定义 Swagger UI 的外观？
您可以通过index.html文件或通过提供自定义 CSS 文件来自定义 Swagger UI 的外观。 -
如何保护我的 API 免遭未经授权的访问？
要保护您的 API 免遭未经授权的访问，您可以在 Web API 中实施身份验证和授权机制。 -
是否有其他工具可用于生成 API 文档？
是的，除了 Swagger UI 之外，还有其他工具可以生成 API 文档，例如 Postman 和 ReDoc。
