其他(Representational State Transfer)是一个接口系统之间使用 HTTP 获取数据并生成 HTTP 操作在所有可能的格式,比如 JSON,这是常用的格式发送和获取数据。
**在本章结束时，你将已经创建了一个 ASP.NET Core 5 Web API，了解了Program.cs文件在 asp.net 中的职责.NET Core 项目，学习了如何使用该项目的Startup.cs文件，并尝试了新的内置 API 文档.NET Core Web API。
在本章中，我们将涵盖以下主题:
- 创建一个 ASP.NET Core 项目
- 理解
Program.cs文件 - 解密
Startup.cs文件 - 开始与 Swashbuckle
以下是完成本章所需要的内容。
- 用于构建后端:Visual Studio 2019, Visual Studio For Mac，或 Rider
- 搭建一个项目:.NET Core CLI
您将在这里创建的项目还不是真实的后端 ASP.NET Core 应用，你将与 Vue.js 连接。 这样做的目的是查看在新创建的 ASP 中有哪些默认文件和文件夹。 网的核心项目。
您将使用命令行而不是 IDE 来确保其他开发人员尝试使用 ASP.NET Core 在 Windows、Mac 或 Linux 上也会得到相同的结果。
要启动该项目，请遵循以下简单说明:
-
在电脑的任何地方创建一个文件夹; 它可以在您的桌面或您的
Download目录中。 我通常把我的测试或演示应用放在Download文件夹中，以便轻松找到并删除它们。 -
将文件夹命名为
DemoProject，然后打开该文件夹。 -
Next, open your command-line terminal and navigate to the directory. There are many ways to do this efficiently. The following are the tools that I can recommend for opening a command line in a specific folder:
Windows 用户:https://hyper.is/
Mac 用户:https://hyper.is/或https://iterm2.com/，openinteral 工具:https://github.com/Ji4n1ng/OpenInTerminal。
Ubuntu Linux 用户:默认内置 openinternal。
如图图 3.1所示，在指定的文件夹上右键点击鼠标，打开我的命令行:
图 3.1 -在这个文件夹中打开 Hyper
导航到创建应用的DemoProject文件夹后，使用上一章安装的。net Core 命令行运行以下命令:
dotnet new slndotnet new webapi --name Webdotnet sln add [csproj-file-location]dotnet run Web.csproj
第一个命令创建一个解决方案文件，该文件将跟踪和组织 Visual Studio 中的项目。 您的 IDE 将使用此解决方案文件作为不同项目的容器，例如类库、可执行应用、网站或单元测试项目。 CLI 使用您创建的文件夹的名称，即DemoProject:
dotnet new sln
在使用。net CLI 运行这个命令之后，您应该在DemoProject文件夹中看到一个DemoProject.sln文件。
第二个命令创建一个 ASP.NET Core 5 Web API 项目，包含运行应用的样板:
dotnet new webapi --name Web
这个命令有点不说明问题，它指示 CLI 创建一个新的 Web API 项目并将其命名为Web。
您应该会看到一个名为Web的文件夹，其中包含 ASP.NET Core Web API 项目称为Web，也匹配它的文件夹。
第三个命令将Web项目添加到解决方案文件中。 在现实的企业开发中，经常可以看到多项目解决方案:
dotnet sln add [csproj-file-location]
dotnet sln add ./Web/Web.csproj适用于 Linux 和 Mac 用户，dotnet sln add .\Web\Web.csproj适用于 Windows 用户。
现在导航到Web目录。 你可以运行以下命令:
cd Web
如果您在 Windows 中使用本机 CMD，则cd命令将不可用。 我建议使用包含在 Windows Git 安装中的bash 终端。 bash 终端在目录树中使用正斜杠。
好的，你应该已经在路径上了-./DemoProject/Web。 现在让我们移动到下一个命令。
这个命令在开发应用时非常有用，它将运行源代码应用。 该命令通过在dotnet run命令前隐式运行dotnet restore来自动解析应用的 NuGet 依赖:
dotnet run Web.csproj
现在转到浏览器并输入以下 URL:https://localhost:5001/weatherforecast。 您的浏览器可能会提示您一条消息，说此站点不安全。 允许 ASP 开发证书.NET Core 创建后，单击浏览器弹出的Accept按钮。 您只需要这样做一次，因为您的浏览器将为您记住证书。
JSON 响应，由JSONviewChrome/Firefox 扩展格式化，应该在您的浏览器中可见。 不要期望每个对象的每个属性都有相同的值; controller方法在返回响应之前将这里的值随机化。 如果您对JSONView扩展感兴趣，可以从https://jsonview.com/获得。
下面的代码是 JSON 响应，你将从点击https://localhost:5001/weatherforecast使用你的浏览器:
[
{
"date": "2020-10-12T12:21:55.5119059+02:00",
"temperatureC": -19,
"temperatureF": -2,
"summary": "Scorching"
},
{
"date": "2020-10-13T12:21:55.5123846+02:00",
"temperatureC": 32,
"temperatureF": 89,
"summary": "Sweltering"
},
{
"date": "2020-10-16T12:21:55.5123876+02:00",
"temperatureC": 6,
"temperatureF": 42,
"summary": "Sweltering"
},
]
您可以通过查看WeatherForecastController.cs文件(您可以在Web/Controllers/中找到)来查看 JSON 响应是如何生成并返回到客户机的。 我们将在第 5 章，设置 DbContext 和控制器中更多地讨论控制器。
我们已经创建了一个 ASP.NET Core 5 项目使用。NET CLI。 现在，让我们转到下一节，了解Program.cs文件及其在 ASP 中的工作.NET Core Web API 项目。
Program.cs文件位于Web项目根目录下的，负责执行Main方法，作为应用的入口点并启动应用。
以下代码存在于Program.cs文件中，我们将其分解为可消化的内容:
namespace Web
{
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
}
如您所见，namespace是以项目的名称命名的。 接下来是Program课。 您可能会注意到，带有Main方法的Program类类似于. net 控制台应用，因为 ASP.NET Core Web API 确实是一个控制台项目，在构建 Web 应用时具有不同的依赖关系。
看看static Main方法的内部。 您可以看到，Main只是简单地调用CreateHostBuilder(args).Build().Run()，这是以下代码块:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
前面的代码使用来自Startup类的配置创建了WebHostBuilder的实例，我们将在下一节中讨论。 静态的CreateHostBuilder方法最终由Main方法构建并运行。
简化 web 应用的初始引导并不是Program.cs文件的唯一任务。 您可以设置其他配置，例如自定义日志记录、环境变量、Azure Key Vault 配置、内存中的。net 对象、Azure App 配置、命令行参数、目录文件、客户提供商等等。
现在您已经知道了Program.cs对 ASP 的贡献.NET Core 项目，我们可以继续下一节，它涉及到Startup.cs文件。
Startup.cs文件位于 web 项目的根文件夹，在应用启动时首先执行。 文件内部的代码如下:
namespace Web
{
public class Startup
{
public Startup(IConfiguration configuration)…
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)…
public void Configure(IApplicationBuilder app,
IWebHostEnvironment env)…
}
}
让我们一个一个来看看。
您将看到的第一个代码块是Startup构造函数，它接受IConfiguration接口并将其赋值给公共IConfiguration``Configurationgetter。 Configuration属性表示每当Startup类实例化时，都会出现Configuration实参。
继续，您将发现包含在Startup.cs文件中的两个公共方法——ConfigureServices和Configure。
让我们先来看看ConfigureServices。 您会发现许多在线博客将ConfigureServices方法描述为一个位置，在该位置您可以用内置的控制反转(IoC)容器插入类。 每当我做一些研讨会和培训时，我发现我的听众很难理解。 所以，我尽量简化它。
ASP.NET Core 提供了一个内置的 IoC 容器，它可以帮助你在类的任何部分中使用服务。 我将给您一个可以使用ConfigureServices方法的用例。 假设你喜欢在你的 ASP 中使用库或 sdk，比如 GraphQL、OData 和 Identity.NET Core 应用。 你可能会去谷歌和搜索如何实现提到的库或 sdk，对吗? 你最终会进入 NuGet 包库。
在大多数情况下，您必须安装 NuGet 包，然后在ConfigureServices方法中注册这个包。 通常，你会写services.AddTheFeatureOfTheInstalledNuget。 键入services，然后是句号，您将看到通过 IDE 的智能感知特性的帮助安装的 NuGet 包的接口。
services.AddSomething是 ASP 的 IoC 部分.NET Core，在这里注入将要使用的工具的接口。 简单地说，在程序中注入依赖关系就是 IoC。 IoC 本身是一个很大的话题，所以我建议在https://auth0.com/blog/dependency-injection-in-dotnet-core/阅读更多关于它的内容，以避免我们偏离本章的主题太远。
方法还内置了 ASP 的服务或实用程序。 净的核心。 你现在可以在你的Startup.cs文件中看到一些好的例子如下:
services.AddControllers()，其中为 API 配置带有控制器的 MVC 服务。services.AddSwaggerGen()，其目的是在您的 ASP. php 中添加 API 文档。 自动 NET Core。 您将在开始使用 Swashbuckle一节了解更多信息。
以下是Startup.cs文件中ConfigureServices方法的代码块或逻辑:
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "Web",
Version = "v1" });
});
}
这里，ConfigureServices接受一个IServiceCollection接口，该接口公开了 ASP 中所有可用的服务。 在 NET Core 中，任何服务只需要一个调用就可以启用。 IServiceCollection启用Controllers和SwaggerGen，如您在ConfigureServices方法内部所看到的。
现在让我们检查Configure方法。
Configure方法允许将中间件添加到应用的请求管道中。 在前端应用或另一个服务到达控制器之前，您可以在此方法中修改它的 HTTP 请求。
这个过程是一个请求被您已经安装或创建的函数或组件修改。 这些功能或组件的示例是日志记录器或认证，它们的顺序可能是有序的，也可能是无序的，这取决于您为解决方案构建的逻辑。 现在让我们来看看Configure方法的代码块:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseSwagger();
app.UseSwaggerUI(c =>
c.SwaggerEndpoint("/swagger/v1/swagger.json",
"Web v1"));
}
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
这里的Configure方法带有一个IApplicationBuilder接口，该接口提供了修改或更改 ASP 的请求管道的机制.NET Core 和IWebHostEnvironment，它提供了关于 web 托管环境的信息，其中您的 ASP. NET Core 和IWebHostEnvironment NET Core 正在运行。
现在让我们检查一下这个默认的中间件.NET Core 5 提供:
UseDeveloperExceptionPage()，它显示一个用于调试应用的有用错误页面。UseSwagger()用于 API 文档。 我将在开始使用 Swashbuckle小节的内置 Swagger 集成小节中进一步讨论这个问题。UseSwaggerUI()，允许您查看 api 的一些元信息。
您可以看到if env.IsDevelopment条件只包括开发环境中的前面三个中间件。
这里是在 ASP 中其余的默认中间件.NET Core Web API:
UseHttpsRedirection():重定向 HTTP 请求到 HTTPSUseRouting():添加定义端点的路由功能UseAuthorization():启用 HTTP 请求授权UseEndpoints():定义端点并使用MapControllers()将控制器映射到各自的端点
现在我们已经讨论完里面有什么Startup.cs。 让我们转到本章的最后一个主题，在 ASP 中默认添加的最新特性.NET Core 5 OpenAPI，也被称为 Swagger。
什么是虚张声势? Swashbuckle 是一个 NuGet 包，提供了将 Swagger 添加到 ASP 的简单方法.NET Core Web API 项目。
后端开发人员应该做的事情之一就是创建对开发人员友好的 api。 您可以通过在开发 api 时记录它们来实现这一点。 编写 api 文档对于将要使用您的 api 的开发人员来说是非常重要的，也是很有帮助的。 例如，文档消除了您和 api 消费者之间不必要的问题和答案，从而节省了所有人的时间。
在另一个场景中，您将看到 API 文档是如何充实的，想象一下在一个大团队中工作。 通过编写 api 文档，您的团队成员将有机会快速检查现有的 api，从而避免重复编写相同的 api 浪费时间和金钱。
好的，我已经提到了您可以从 API 文档中获得的主要好处。 下面是我们将要发现的一些东西。
OpenAPI 规范**，以前称为Swagger 规范，是一个规范，用于描述与语言无关的文本、JSON 和 YAML 格式的 api 功能。**
**现在我们知道 OpenAPI 是一个规范，有一个流行的工具使用它产生的 JSON 格式实现它。 这个工具也是 Swagger，但不要与 Swagger 规范混淆; 我现在谈论的 Swagger 是一种工具，它可以使您更容易地创建 API 文档，并帮助您快速集成 API。
现在让我们转到下一节，看看 ASP 的内置 Swagger 集成.NET Core 5 优惠。
ASP.NET Core 5 已经正式包含了Swashbuckle包，它将 Swagger 集成到的 ASP. NET Core 5 中。 Microsoft.Extensions.DependencyInjection命名空间中的 NET Core Web API。 在搭建应用时，Swagger 会通过。net CLI 自动为你安装。你可以在Web.csproj的ItemGroup中看到它:
<PropertyGroup>
<TargetFramework>net5.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore. Authentication.JwtBearer" Version="5.0.2" NoWarn="NU1605" />
<PackageReference Include="Microsoft.AspNetCore. Authentication.OpenIdConnect" Version="5.0.2" NoWarn="NU1605" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3" />
</ItemGroup>
在前面的代码中，您可以看到有一个对Swashbuckle.AspnetCore version 5.*.*的包引用。 因此，它可以随时使用。
此外，在 ASP 中启用 Swagger。 默认情况下。NET Core 5 Web API 项目。 打开Startup.cs文件，查看以下代码中的AddSwaggerGen扩展名:
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo {Title="Web", Version="v1" });
});
AddSwaggerGen是一个服务的扩展，可以让 Swagger 生成器构建SwaggerDocument对象。 您还可以找到SwaggerDoc扩展，它添加了一个 url 友好的名称，通过传递以下两个参数来识别文档:
"v1"new OpenApiInfo { Title = "Web", Version = "v1" });
当使用SwaggerDoc扩展时，这个v1字符串类型和OpenApiInfo对象是必需的参数。 此外，OpenApiInfo要求您向Title和Version属性中添加值，以便向 Swagger 文档中添加一些元数据。 现在让我们进入中间件部分。
在Configure方法中有两个现成的中间件:
UseSwagger():生成 OpenAPI 文档的中间件UseSwaggerUI():渲染 Swagger UI 网页
你可以在这里看到UseSwagger和UseSwaggerUI中间件的作用:
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseSwagger();
app.UseSwaggerUI(
c => c.SwaggerEndpoint("/swagger/v1/swagger.json",
"Web v1"));
}
不过，在UseSwaggerUI中间件中还需要添加一个。 您必须通过SwaggerEndpoint扩展在UseSwaggerUI中指定文档的路径和版本。
在下一节中，我们将了解如何打开或查看由 ASP 提供的 Swagger 文档样本。 净的核心。
在查看了Startup.cs文件的代码之后，让我们检查一下 Swagger 文档和 Swagger UI。
我们将运行应用来查看 Swagger 文档和 Swagger UI。 我们还将测试 API，以确定它向我们这样的开发人员显示的用户界面。 请依次执行以下步骤完成本节操作:
-
检查您的 ASP.NET Core 5 仍在运行。 如果您的项目没有运行，请在
Web文件夹中运行以下命令:dotnet run Web.csproj -
Head to the following URL,
https://localhost:5001/swagger/v1/swagger.json, in your browser. As shown in Figure 3.2, you will see the generated Swagger JSON document describing theWeatherForecastendpoint:
图 3.2 - Swagger 文档
如果您注意到前面截图中的，那么 URL 版本与 Swagger 文档版本、OpenAPI 版本、标题以及
OpenApiInfo对象定义的版本相匹配。您还将在 ASP 中找到单个默认控制器.NET Core 5 项目
WeatherForecast，以及它的GET方法。 -
Now, navigate to the Swagger UI: https://localhost:5001/swagger/index.html. The Swagger UI in Figure 3.3 is the interactive web form of the Swagger documentation. You should see on your screen the same image as Figure 3.3:
图 3.3 - Swagger UI
Swagger UI 允许开发人员发现控制器的细节和控制器的模式。 在前面的截图中，你只看到一个控制器和一个模型，因为这就是 ASP.NET Core 5 为您提供了开箱即用的。
-
Click the
GETmethod to see its info. Your screen should look like this:
图 3.4 - Swagger UI
屏幕截图描述了所选 HTTP 方法的参数、响应码、媒体类型、示例值、模式等信息。 您将注意到，媒体类型默认设置为文本/普通。 如果需要，可以将其更改为application/json。
-
Click the Try it out button to show the UI to test the
GETmethod:
图 3.5 - Swagger UI
点击Try it out按钮后，会出现宽的Execute按钮，正如在图 3.5中所看到的。 我们可以尝试 HTTP
GET方法以查看它是否命中端点并使用200进行响应。 -
Click the Execute button, and then observe the UI:
图 3.6 - Swagger UI
单击Execute按钮后，您应该看到一个与图 3.6相似的屏幕。 您可以看到 curl CLI，这是图像顶部区域中用于 URL 操作的工具，这意味着您可以通过在终端上运行
curl命令来点击端点，并将看到相同的响应。您还可以在
curl命令之后找到准确的请求 URL 或端点，对于服务器响应，您将在图像上发现 JSON 格式的响应体。 -
在这一部分中，除了滚动之外，您不需要做任何事情。 在 UI 中向下滚动查看其余响应。 您还可以在这里找到响应头，它告诉您内容类型、数据和服务器。
-
Now let's move down to the Swagger UI schemas to investigate what we can find there. Click the WeatherForecast dropdown, as shown in Figure 3.7. You should see that the properties of
WeatherForecastare the same as the image, which aredate string,temperatureC integer,temperatureF integer, andsummary string:
图 3.7 - Swagger UI
-
最后，回到你的 ASP。
WeatherForecast类在WeatherForecast.cs文件中:public class WeatherForecast { public DateTime Date { get; set; } public int TemperatureC { get; set; } public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); public string Summary { get; set; } } -
将
WeatherForecast类的形状与 Swagger UI 中的WeatherForecast模式进行比较。 它们应该是一样的。
以上就是我们对来自Swashbuckle包的 Swagger 文档和 Swagger UI 的讨论。 现在，让我们总结一下本章所学的内容。
通过这些，您已经学会了如何轻松地创建 ASP.NET Core 5 项目，没有 IDE。
您已经了解了Program.cs文件的工作方式、执行主方法和启动应用。 您还发现了Startup.cs文件的职责:通过内置的依赖注入来启用服务，并按顺序收集所有运行的中间件。
最后，您已经看到了 ASP 的新特性.NET Core Web API 项目。
ASP。 当您创建 Web API 项目时，NET Core 5 会立即为您设置 Swagger 文档。 您已经看到了 Swagger 文档在帮助开发人员查看现有 api 并检查其详细信息方面的重要性。
在下一章中，我们将创建另一个。net 解决方案和项目，并记住清晰的体系结构。****