在 Angular 中使用 Swagger [关闭]

Question

我是 Swagger 的新手，据我所知，它用于自动生成 API 文档。除此之外，我认为它还用于使用 Swagger Codegen 生成前端。在这一步，我对在我的项目中正确使用 swagger 感到困惑。

我已使用 .NET Core 创建了后端，并且 API 方法已准备就绪。现在，我需要将 swagger 集成到我的项目中。我有一个初始的 Angular 前端应用程序，但由于代码混合，我想从 stratch 创建前端，然后将 Swagger 集成到它。所以;

1. 我应该使用必要的 Swagger 工具生成前端吗？好像不太好，但是如果一般用，随着项目变大不会有问题，当然可以用那个选项。

2. 如果我从 stratch 创建 Angular 项目，如何集成 swagger？是否应该使用相关组件的ts文件生成代码？

3. 如果我将新组件添加到前端，并将相应的 API 方法添加到已经使用 Swagger 的 API。我应该做哪些修改？我试了一下，它在构建项目后生成了一个新的 swagger 配置文件。

Answer 1

继续我在问题下方制作的 cmets。

只是为了澄清一下swagger和openApi是什么，swagger既是一个rest api规范（例如swaggerSpec.Json），也是一套处理规范的工具。例如，swagger codegen、swagger UI 等。现在在某个时间点，规范从 swagger 重命名为 OpenApi。

也就是说规范叫做OpenApi，swagger是一套处理openApi的工具。

来源：https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/

除了 swagger 之外，还有一组替代工具，例如 NSwag 和 Swashbuckle，它们可以使使用 openApi 规范更容易。

有两个主要部分：

• openApi 规范的代码生成。您可以从 OpenApi 文档生成服务器代码（例如 ASP.NET 核心休息控制器），并从 OpenApi 文档生成客户端（例如 C# 休息客户端、.TS 休息客户端、Java）。或者您可以从例如生成 OpenApi 规范（我的 SwaggerSpec.json）本身。您的 .net 核心项目和一些工具。
• (Web)Ui 可轻松托管文档。 Swagger 有 webUI、NSwag，甚至还有像 https://github.com/Redocly/redoc 这样的替代工具，所有这些都包括一种轻松测试您定义的 Api 端点的方法。通常，这些文档站点是独立的东西。它们可能在样式方面进行了配置，但您通常保持不变。你当然可以自己动手 - 或克隆任何 ui 存储库并更改它 - 但那是另一个主题。

我已经调查了所有 3 个选项（Swagger、SwashBuckle 和 NSwag），我选择了 NSwag，因为当时 a）它是我开始工作的一个，b）它具有最多的功能，c）社区相当积极的。这是大约一年前的事了。

我将解释我的工作流程，这应该可以回答您的大多数问题。我觉得这个问题变得相当广泛，所以请做一些挖掘工作并尝试根据您的需求定制更具体的问题。

就像我说的，我使用 NSwag 工具链：

1. 我在我的服务器应用程序中创建 Asp.Net 控制器。 这包含控制器功能/端点的一些属性，因此可以更好地生成 swagger 规范：

2. 然后我使用 NSWag studio 创建一个 openApi 文档文件

输出：

1. 此时您可以选择再次使用 NSwag 来生成例如 typescript 客户端，然后您可以在 angular/react w/e 前端项目中使用它：

4. 然后我将 swagger 文档添加到我的 asp.net 服务器项目中，并启用 swagger UI：

Startup.cs 中的某处：

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IOptions<AppSettings> appSettingsAccessor, ILogger<Startup> logger, StaticFileConfigSection staticFileConfig)
        {
            // Add the openApi document and serve the swagger dashboard.
            app.UseOpenApi();
            app.UseSwaggerUi3(); // serve Swagger UI 
         ...

然后我可以去 /swagger 查看 web ui：

就是这样。当然，所有这些工具都可以自动化——但我选择不这样做。让它发挥作用可能很麻烦，而且使用 NSwag 工作室，我总是按一下按钮。这迫使我在工作上更加小心。

Answer 2

1. 使用 Codegen 是您的选择。您可以使用生成的代码作为样板来直接开始您的 API 集成。您可以只复制生成的模型和服务并集成它们。它将为您节省大量编码时间，并避免服务编码中的人为错误。但是前端的其余部分可以是您喜欢的任何东西，不一定是生成的项目。例如，您可以使用选择的 Angular 种子并仅集成来自 Codegen 的服务。
2. 正如我所提到的，您可以从 Cogeden 复制生成的服务和模型，以抢占先机。如果您决定完全手动，则必须使用 Angular HTTP 向服务器发出请求 (https://angular.io/guide/http)。您必须手动定义模型和服务才能对实体进行操作。在这种情况下，Swagger 仅作为 API 的参考，与 Angular 完全没有集成。我不鼓励这个选项，除非 Codegen 生成的库不够用。如果 Swagger 设计正确（遗憾的是这种情况很少见），遵循所有标准并提供完整的数据模型，您就可以信任生成的库。
3. 这是建议而非客观指导：如果 API 的更新很小，请直接在您的代码中进行更新，并使用新的更改更新您的 Swagger。如果更改是相关的，您需要一个具有不同端点的新主要 API 版本。在这种情况下，生成一个新的 Swagger Codegen 库并将其放置在旧库的位置将是一个好主意。为了能够做到这一点，您必须避免修改生成库的服务内部，尽可能“按原样”使用库。