如今，以下方法被广泛用于描述浏览器和服务器的交互，例如OpenApi和GraphQL。
在本文中，我将讨论我们试图创建一个静态类型的REST API，并使前端团队免于编写用于编写数据请求的代码，简化测试并减少可能的错误数量的尝试。
这些工具可以帮助我们：
- 根据规范设计和建模API以符合标准
- 使用几乎所有语言为您的API创建稳定，可重用的代码
- 通过交互式API文档改善开发人员体验
- 在您的API上轻松执行功能测试。
- 在您的API体系结构中创建并应用最佳的API样式指南
该方法的主要思想是，在客户端和服务器上具有相同的数据类型，团队中的开发人员在客户端上犯错误更加困难，并且使用代码生成无需编写，维护和覆盖单元测试。
如果该命令在REST API接受/提供的数据类型中出错，则前端应用程序将无法编译。
因此，在客户端上使用静态类型的代码，我们可以摆脱与类型相关的愚蠢错误，并确保我们的代码与当前版本的API完全兼容。
为了获得静态类型API的所有上述优点，我们需要使用代码生成器，根据OpenAPI规范，该代码生成器可以生成类型描述文件，对于Typescript，这些文件是* .d.ts文件。
我们的项目使用微服务架构，整个后端都用.NET编写，因此我们使用NSwag为前端/后端生成API客户端。 该工具允许您生成OpenAPI文档，然后依次将其用于生成客户端代码。
建筑学
通常，代码生成过程包括几个阶段：
- OpenAPI文档生成
- 使用OpenAPI文档生成代码
在我们的例子中，后端是使用.Net编写的，而主要的C＃开发语言是由于工具的选择。 我们使用称为NSwag的相同工具来生成OpenAPI文档和客户端。
图1生成剩余客户端代码的解决方案的体系结构该图显示：
- 微服务1 ... N-提供API的微服务
- NSwag-从微服务API代码生成OpenAPI文档（可以使用存在生成OpenAPI文档的工具的任何语言编写微服务）
- NSwag-为OpenAPI文档生成客户端API代码（您可以选择许多工具来更适合您的技术堆栈）
- OpenAPI文档-生成的OpenAPI文档
- API客户端1 ... N-使用API数据的客户端（可以在支持NSwag C＃和Typescript生成器的任何语言上实现）
- SPA 1 ... N-前端应用程序，在我们的案例中是React（NSwag支持AngularJS / Angular的客户端生成，React（获取），JQuery（承诺/回调），Aurelia）
动作顺序如下：
- 根据API的语言，使用适当的标记/属性/修饰符标记API控制器
- 生成OpenAPI API代码文档
- 使用OpenAPI文档生成客户端API代码
- 将客户端API代码集成到数据使用者API应用程序中
该文件
为了能够生成代码，我们需要描述API控制器的接受/返回值的类型，在此示例中，使用SwaggerOperation属性，在使用C＃语言的地方，我们标记了一种方法，该方法将返回服务器上所有调查表的列表，在客户端代码中，这是一种获取方法。该数据将称为GetAllQuestionnaires：
[HttpGet, Route("")] [SwaggerOperation(OperationId = "GetAllQuestionnaires")] [SuccessResponse(typeof(IEnumerable<QuestionnaireViewModel>))] public IEnumerable<QuestionnaireViewModel> Get() { var surveys = _questionnaireRepository.GetAll(); return surveys.Select(QuestionnaireViewModel.ToViewModel).ToArray(); }
清单1描述API方法的示例C＃代码然后，使用NSwag，我们将自动生成一个OpenAPI文档，其中将包含所有在后端代码中标记有相应属性的API端点。
图2 OpenAPI文档因此，我们设法创建了API的始终自动更新的文档。
打字
OpenAPI文档包含有关后端控制器将发送/接收的数据类型的信息。 因此，在前端，我们可以完全依靠后端提供给我们的类型，而不必创建自己的类型，而是从使用OpenAPI文档生成的客户端代码中导入它们。
在我们的示例中，文档包含有关QuestionnaireViewModel类型的信息（此处，为了便于阅读，以HTML格式显示了规范）
图3 OpenAPI文档中的示例数据模型下一步是将此信息传递给前端应用程序代码。
代码生成
我们还使用NSwag生成客户端API代码。 输入时，它将接收OpenAPI文档，并根据指定的设置生成客户端API代码。 首先，在接收到的代码旁边，添加package.json并将其发送到本地npm寄存器。
从后端代码清单（请参见清单1）可以看到，我们使用属性标记了controller方法。
[SwaggerOperation(OperationId = "GetAllQuestionnaires")]
在本例中，在C＃属性中指定的OperationId将成为客户端方法的名称。
图4使用生成的客户端API的示例同样，在生成客户端之后，我们收到了一个d.ts文件，其中包含数据类型的相应描述，如下图所示。
图5 .d.ts文件中的示例数据类型描述现在，在前端应用程序代码中，您可以使用从客户端API代码导出的数据类型，并在代码编辑器中使用自动完成功能，如下图所示。
图6客户端API数据类型信息的使用示例Typescript中的所有相关数据类型验证器也可以使用。
下图中的示例。
图7客户端API数据类型验证示例
图8客户端API数据类型验证示例结论
应用此方法后，我们获得了以下优势：
- 更少的数据类型错误
- 更少的代码，更少的调试，测试，支持工作
- 始终提供有关每个微服务的所有API方法的最新文档
- 能够测试API自动化
- 前端和后端的统一类型系统
参考文献