为什么 HttpRepl 找不到 OpenAPI 描述？命令“ls”不显示可用端点

Question

我正在学习 Microsoft Learn 教程“使用 ASP.Net Core 创建 Web API ”。

在“构建和测试 Web API”标题下的说明 (5) 中，我收到响应“无法找到 OpenAPI 描述”。

对于步骤 (6)，当执行“ls”命令时，我得到响应：“尚未设置目录结构，因此没有可列出的内容。使用‘connect’命令根据 OpenAPI 描述设置目录结构”。我已经尝试了此处建议的“connect”命令，并尝试了“dir”作为“ls”的替代品。

我可以在步骤 (7) 中成功更改目录并执行步骤 (8) 的 GET 请求并收到预期的回复。然而，真正让我困扰的是“ls”命令在这里不起作用，并且似乎是 httprepl 工具的一个重要功能。

我怎样才能让“ls”命令在这里工作或告诉我为什么它不起作用？

C:\Users\xxxx\source\repos\Learn\ContosoPizza>httprepl http://localhost:5000
(Disconnected)> connect http://localhost:5000
Using a base address of http://localhost:5000/
Unable to find an OpenAPI description
For detailed tool info, see https://aka.ms/http-repl-doc

http://localhost:5000/> ls
No directory structure has been set, so there is nothing to list. Use the "connect" command to set a directory structure based on an OpenAPI description.       

http://localhost:5000/>

补充建议结果--

C:\Users\xxxx\source\repos\Learn\ContosoPizza>dotnet --version
3.1.412

C:\Users\xxxx\source\repos\Learn\ContosoPizza>dotnet add WebAPI.csproj package Swashbuckle.AspNetCore -v 5.6.3
Could not find project or directory `WebAPI.csproj`.

httprepl GitHub 存储库和MS 文档页面

Answer 1

对我来说，解决方案是简单地信任 localhost 的 SSL 认证，您可以使用以下命令来执行此操作：

dotnet dev-certs https --trust

在做相同的教程时，我的一个朋友注意到，教程中已经涵盖了信任开发证书，而我自己在做教程时忽略了这一点。这是官方帮助网站： 在 Windows 和 macOS 上信任 ASP.NET Core HTTPS 开发证书。也许这仍然会帮助遇到同样问题的人。

Answer 2

在步骤 5 中HttpRepl发出警告Unable to find an OpenAPI description，这意味着它找不到 swagger 端点，因此该ls命令将不起作用。

我假设您正在使用VS Code和ASP.NET Core 5.0。这是我运行的输出dotnet --version：

5.0.401

如果我们使用Visual Studio，那么请记住在创建项目时启用 swagger - 我使用Visual Studio 2019创建屏幕截图：

指定您的 OpenAPI 描述

要找出要使用的端点，请打开文件Startup.cs并找到包含文本 的代码片段UseSwaggerUI。您应该找到以下代码块：

5.0.401

使用您找到的端点并运行该工具，如下所示：

httprepl http://localhost:5000 --openapi /swagger/v1/swagger.json

如果您没有找到任何对 swagger 的引用，请参阅下面的上述方法均无效，未安装 swagger，了解如何为您的项目安装和配置 swagger。

忽视你的环境

如果指定要使用的 Open API 端点不起作用，则说明您没有在开发环境中运行 Web API。因此，要么使用开发环境，要么在测试时取消注释 if 语句（要设置开发环境，请参阅下面的更改环境）：

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    app.UseSwagger();
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebAPI v1"));
}

请记住在部署到生产环境之前恢复未注释的代码（如果有）。

改变你的环境

您的 Web API 正在使用的配置文件在文件中指定Properties\launchSettings.json。打开文件并搜索ASPNETCORE_ENVIRONMENT. 然后将找到的实例更改为：

"ASPNETCORE_ENVIRONMENT": "Development"

如果这不起作用，或者实例已设置为“开发”，则意味着您没有使用启动设置中指定的任何配置文件。如果未使用配置文件，ASPNETCORE_ENVIRONMENT则默认为“生产”。使用该dotnet run命令时，--launch-profile参数可让您指定要使用的配置文件：

dotnet run --launch-profile "name_of_profile"

ASPNETCORE_ENVIRONMENT作为最后的手段，您可以在运行命令之前在正在使用的 shell 中设置环境变量dotnet run：

重击

export ASPNETCORE_ENVIRONMENT=Development

指令管理系统

set ASPNETCORE_ENVIRONMENT=Development

电源外壳

$env:ASPNETCORE_ENVIRONMENT='Development'

然后在没有配置文件的情况下运行应用程序：

dotnet run --no-launch-profile

在没有配置文件的情况下运行时，默认端口应为 5000 或 5001。但请阅读命令的输出，以查看它分配给您的 Web API 的端口。

请注意，如果您使用VS Code运行项目，则VS Code也可能在.vscode\launch.json. 这取决于您如何配置VS Code以及您允许它执行的操作。我发现了一些旧文章，声称VS Code的一些扩展的某些扩展可能会干扰启动设置，但他们没有指定哪些扩展。

以上均无效，未安装 swagger

如果以上都不起作用，则意味着您没有安装 swagger。为您的项目安装 swagger，完成后重试。

包安装

在VS Code中打开您的项目，然后从集成终端运行以下命令，并将WebAPI.csproj替换为您自己的项目文件的名称：

dotnet add WebAPI.csproj package Swashbuckle.AspNetCore -v 5.6.3

您当然可以从VS Code外部运行该命令，并将项目文件夹作为当前工作目录。

添加并配置 Swagger 中间件

将 Swagger 生成器添加到方法中的服务集合中Startup.ConfigureServices，如方法中的最后一条语句：

httprepl http://localhost:5000 --openapi /swagger/v1/swagger.json

在该Startup.Configure方法中，在方法顶部启用中间件来提供生成的 JSON 文档和 Swagger UI：

//if (env.IsDevelopment())
//{
    app.UseDeveloperExceptionPage();
    app.UseSwagger();
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebAPI v1"));
//}

了解有关设置 swagger、配置文件和环境的更多信息

Swashbuckle 和 ASP.NET Core 入门
在 ASP.NET Core 中管理生产和开发设置 在 ASP.NET Core
中使用多个环境
通过 Swagger / OpenAPI 实现 ASP.NET Core Web API 文档