asp.net - 在 Angular 中使用 Swagger

Question

关闭。这个问题需要多问 focused 。目前不接受答案。

---

想要改进此问题吗？更新问题，使其仅关注一个问题 editing this post .

已关闭 3 年前。

Improve this question

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

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

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

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

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

Answer 1

继续讨论我在问题下发表的评论。

为了澄清什么是 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 Core Rest Controller )，并从 OpenApi 文档生成客户端代码(例如 C# Rest 客户端、.TS Rest 客户端、java)。或者您可以直接生成 OpenApi 规范(我的 SwaggerSpec.json)本身，例如您的 .net core 项目以及一些工具。
• (Web)Ui 可轻松托管文档。 Swagger 有 webUI、NSwag，甚至还有替代工具，如 https://github.com/Redocly/redoc所有这些都包括一种轻松测试您定义的 Api 端点的方法。一般来说，这些文档站点是独立的。它们可能是按样式配置的，但通常您不会更改它们。您当然可以推出自己的 - 或克隆任何 ui 存储库并进行更改 - 但那是另一个主题。

我研究了所有 3 个选项(Swagger、SwashBuckle 和 NSwag)，我选择了 NSwag，因为当时 a) 它是我工作的那个，b) 它具有最多的功能，c) 社区相当不错积极的。这是大约一年前的事。

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

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

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

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

输出:

此时，您可以选择再次使用 NSwag 来生成例如 typescript 客户端，然后您可以在 Angular/React w/e 前端项目中使用该客户端:

然后，我将 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 studio 中我总是只需点击一下按钮即可。这迫使我对工作更加小心。