使用NSwag生成TypeScript客户端时{controller}占位符失效问题

我基于OpenApi规范生成TypeScript客户端，使用NSwagStudio创建配置文件时保留默认的{controller}Client设置，但该占位符未生效，生成的类名仅为Client。请问可能的问题是什么？

配置文件片段 #

"codeGenerators": {
   "openApiToTypeScriptClient": {
     "className": "{controller}Client",
      "operationGenerationMode": "MultipleClientsFromOperationId",
...

后端控制器代码片段 #

[ApiController]
public class WorkoutsController : ControllerBase
{
    private readonly IWorkoutService _workoutService;

    public WorkoutsController(IWorkoutService workoutService)
    {
        _workoutService = workoutService;
    }

    [ProducesResponseType(StatusCodes.Status404NotFound)]
    [ProducesResponseType(typeof(WorkoutResponse), StatusCodes.Status200OK)]
    [HttpGet(ApiEndpoints.Workouts.Get)]
    public async Task<IActionResult> Get([FromRoute] Guid id, CancellationToken token)
    {
        var workout = await _workoutService.GetByIdAsync(id, token);
        if (workout is null)
            return NotFound();

        var workoutResponse = workout.ToWorkoutResponse();
        return Ok(workoutResponse);
    }
...

OpenApi规范片段 #

{
    "openapi": "3.0.1",
    "info": {
        "title": "fitflow.RestApi",
        "version": "1.0"
    },
    "paths": {
        "/api/workouts/{id}": {
            "get": {
                "tags": [
                    "Workouts"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "style": "simple",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "$ref": "#/components/schemas/WorkoutResponse"
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WorkoutResponse"
                                }
                            },
                            "text/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WorkoutResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            },
                            "text/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/workouts": {
...

可能的问题及解决方案 #

• 操作生成模式与占位符解析逻辑不匹配
  你当前设置的operationGenerationMode为MultipleClientsFromOperationId，这个模式下NSwag会从接口的OperationId中提取控制器名称来填充{controller}占位符，但你的OpenApi规范中没有定义任何OperationId，后端接口也没显式设置，导致NSwag无法识别控制器名称，只能生成默认的Client类名。

  解决方法二选一：

  1. 修改operationGenerationMode为MultipleClientsFromTag：你的接口已经带有tags: ["Workouts"]标签，这个模式会直接使用tag名称作为控制器名称，填充后会生成WorkoutsClient类。
  2. 给后端接口添加OperationId：在HttpGet特性中指定Name属性，比如[HttpGet(ApiEndpoints.Workouts.Get, Name = "Workouts_Get")]，生成的OpenApi会包含该OperationId，NSwag就能从中解析出Workouts作为控制器名称。

• OpenApi元数据缺失控制器关联信息
  后端控制器名为WorkoutsController，但生成的OpenApi规范中没有将控制器名称与接口绑定的元数据（除非配置了ASP.NET Core的Swagger生成选项）。如果不切换到MultipleClientsFromTag模式，NSwag无法从现有OpenApi内容中获取到控制器名称。

• 占位符仅在特定模式下生效
  {controller}占位符并非在所有operationGenerationMode下都有效：

  • SingleClient模式：不会区分控制器，直接使用配置的类名（即跳过占位符解析，生成Client）
  • MultipleClientsFromOperationId：依赖OperationId的命名格式（如{Controller}_{Action}）来提取控制器名称
  • MultipleClientsFromTag：依赖接口的tag字段来填充控制器名称

内容的提问来源于stack exchange，提问作者Valentin Vadász