DEV Community
·
使用OpenAPI和Orval从.NET 9 API生成TypeScript客户端
内容提要
本文介绍了如何为.NET API服务自动生成强类型的TypeScript客户端。首先创建API项目并添加OpenAPI和Scalar包，然后生成API描述文件并在构建后复制到输出目录。最后，使用orval生成TypeScript客户端，生成的文件包含API调用的类型定义。
关键要点
-
介绍如何为.NET API服务自动生成强类型的TypeScript客户端。
-
创建API项目并添加OpenAPI和Scalar包。
-
生成API描述文件并在构建后复制到输出目录。
-
使用orval生成TypeScript客户端，生成的文件包含API调用的类型定义。
-
创建解决方案和WebAPI项目的步骤。
-
添加OpenAPI包以生成API描述。
-
安装Microsoft.Extensions.ApiDescription.Server包以生成OpenAPI参考文件。
-
在构建后将DemoApi.json文件复制到输出目录。
-
使用orval生成TypeScript客户端的准备步骤。
-
创建orval.config.js以配置客户端生成。
-
使用命令生成TypeScript客户端文件和API调用的类型定义。
延伸解读
OpenAPI与Scalar的选择
微软最近推出了自己的API描述生成器，减少了对Swashbuckle Swagger的依赖。这一变化虽然引发了一些争议，但在商业化趋势下，使用微软的工具可能会带来更好的支持和更新。开发者在选择工具时应考虑长期维护和社区支持的因素。
CI/CD中的文件管理
在CI/CD流程中，DemoApi.json文件仅生成于obj文件夹，这可能导致前后端分离构建时无法找到该文件。开发者需要在构建后复制该文件，或调整.csproj文件以确保文件在正确的位置。这一过程可能会增加构建复杂性，需谨慎处理。
TypeScript客户端生成的灵活性
使用orval生成TypeScript客户端时，开发者可以根据需求选择不同的HTTP库（如axios或fetch）。这种灵活性使得前端开发者能够根据项目需求定制API调用方式，提高了代码的可维护性和适应性。
延伸问答
如何为.NET API服务生成TypeScript客户端？
首先创建API项目并添加OpenAPI和Scalar包，然后生成API描述文件并在构建后复制到输出目录，最后使用orval生成TypeScript客户端。
在创建API项目时需要添加哪些包？
需要添加Microsoft.AspNetCore.OpenApi和Scalar.AspNetCore包。
如何生成API描述文件？
安装Microsoft.Extensions.ApiDescription.Server包后，构建项目会在obj文件夹中生成DemoApi.json文件。
如何在CI/CD中处理生成的DemoApi.json文件？
可以在CI/CD步骤中复制该文件，或修改.csproj文件以确保文件被正确复制到输出目录。
orval的配置文件如何创建？
创建orval.config.js文件，配置输入为API描述文件路径，输出为生成的TypeScript客户端文件和模型。
生成TypeScript客户端的命令是什么？
使用命令node .\node_modules\orval\dist\bin\orval.js --config .\orval.config.js来生成TypeScript客户端。
