如何基于OpenAPI规范创建并实现.NET 8 API？

核心生成工具：.NET官方OpenAPI代码生成器 #

.NET 8自带的dotnet openapi命令是从OpenAPI规范生成服务端代码的原生方案，完全适配.NET生态，无需额外安装第三方工具链。

生成步骤 #

1. 将Stoplight导出的OpenAPI YAML文件放到项目根目录（或指定路径），比如命名为api-spec.yaml
2. 在终端执行生成命令：

   # 本地文件生成服务端代码
   dotnet openapi add file ./api-spec.yaml --code-generation-mode server
   # 可指定命名空间避免冲突
   dotnet openapi add file ./api-spec.yaml --code-generation-mode server --namespace YourOrg.Api.Contracts
   

3. 执行完成后，项目中会自动生成：
   • 与规范完全对应的API接口定义（如IXXXApi.cs），包含所有端点的路由、参数、请求体、响应类型
   • 所有规范中定义的模型类（DTO），自动处理数据校验规则
   • 基础控制器骨架（可直接继承接口实现业务逻辑）

可实现接口的说明 #

生成的接口是完全可落地的：所有端点签名严格匹配OpenAPI规范，你只需要创建控制器类继承该接口，实现接口内的方法即可，无需手动编写路由属性、参数绑定或模型定义，从根源避免手动编码的错误。

示例实现：

[ApiController]
public class UserApiController : IUserApi
{
    private readonly IUserRepository _userRepository;

    public UserApiController(IUserRepository userRepository)
    {
        _userRepository = userRepository;
    }

    public async Task<ActionResult<UserDto>> GetUserById(string userId)
    {
        var user = await _userRepository.GetById(userId);
        return Ok(user);
    }
}

最佳实践 #

• 分离契约与实现：将生成的接口和模型类放到单独的类库项目（如YourOrg.Api.Contracts），业务实现控制器放在主API项目中，后续规范更新重新生成时不会覆盖业务代码
• 禁止修改生成文件：生成的接口和模型是规范的映射，手动修改会导致与规范不一致，更新规范后直接执行dotnet openapi refresh重新生成即可
• 启用Nullable参考类型：在项目文件中开启<Nullable>enable</Nullable>，与生成代码的空值处理逻辑兼容，减少空引用异常
• 依赖注入解耦：将实现类注册到DI容器，通过接口注入到控制器，符合依赖倒置原则
• 校验规范一致性：生成代码前，可通过dotnet openapi validate命令校验规范文件的合法性，避免无效规范生成错误代码

内容的提问来源于stack exchange，提问作者JensB