在角度上使用摆动

Question

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

我已经使用.NET核心创建了我的后端，并且已经准备好了。现在，我需要将swagger集成到我的项目中。我有一个初始的角前端应用程序，但是由于代码是混合的，我想从stratch创建前端，然后将Swagger集成到其中。是这样的；

1.应该使用必要的Swagger工具生成前端吗？它似乎不是很好，但如果它是普遍使用，不会成为一个问题，因为项目变得更大，当然，我可以使用这个选项。

2.，如果我从stratch创建了一个角度项目，我如何才能集成这个swagger？我应该使用相关组件的ts文件生成代码吗？

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

Answer 1

我在下面的问题上发表了一些评论。

为了澄清swagger和openApi是什么，swagger既是rest规范(例如swaggerSpec.Json)，也是处理规范的一组工具。例如，swagger，swagger等等。现在，在某个时候，规范从swagger重命名为OpenApi。

这意味着规范称为openApi，swagger是一组处理OpenApi的工具。

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

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

主要有两个部分：

为规范生成

• 代码。您可以从一个ASP.NET文档为服务器(例如OpenApi核心rest控制器)生成代码，从OpenApi文档生成客户机(例如C# rest客户端、.TS rest客户端、java名称)。或者，您可以通过一些tooling.
• (Web)Ui来生成OpenApi规范(MySwaggerSpec.json)本身，例如，您的.net核心项目，以便轻松地保存文档。Swagger有webUI、NSwag，甚至还有替代工具(如https://github.com/Redocly/redoc )--所有这些都包括一种轻松测试您定义的Api端点的方法。一般来说，这些文档站点是独立的东西。它们可能是按风格配置的，但您通常不会碰它们。当然，您可以自己滚--或者克隆任何ui回复并修改它--但这是另一个主题。

我研究了所有三个选项(Swagger、SwashBuckle和NSwag)，我选择了NSwag，因为在当时( a)它是我工作的那个，( b)它具有最多的特性，( c)社区相当活跃。这是一年前的事了。

我将解释我的工作流程，这将回答你的大部分问题。我觉得这个问题越来越广泛，所以请你四处挖掘一下，试着找出更多适合你需要的具体问题。

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

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

。

然后使用

1. I使用NSWag studio创建openApi文档文件

​

​

输出：

​

此时，您可以选择再次使用

1. 来生成一个类型记录客户机，然后您可以在您的角/响应w/e前端项目中使用该客户机：

​

​

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

在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：

​

​

就是这样。当然，所有这些工具都可以自动化--但我选择了不这样做。要让它发挥作用是一件很麻烦的事情，而对于NSwag工作室，我总是按一下按钮就可以了。这迫使我对我的工作更加小心。

Answer 2

使用Codegen的

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