Operation Schema inconsistencies

[RadderTim]

I'm running into issues with generating operation schemas. I'm trying to separate operation schemas into their own folder, but when I generate the schemas, almost everything is just going into the base schema directory. Is Orval deciding what is Operational and what isn't based solely on the naming convention?

As an example endpoint in my NestJS backend, I have a route that has @ApiResponse(), @Param(), and @Query(). When Orval generates the schemas for this endpoint, the response is in the regular schema folder, the params are moved to be in the axios-function itself, and then the query gets added as an operational schema that gets called {endpointName}Param .

@ApiParam({
  name: 'accountId',
  description: 'Account ID',
  required: true,
  type: Number,
})
@ApiParam({
  name: 'houseId',
  description: 'House ID',
  required: true,
  type: Number,
})
@ApiQuery({
  name: 'dogBreedId',
  required: true,
})
@Get('/:house-id/latest-dog')
@UseGuards(ReadHouseGuard)
@ApiResponse({
  status: 200,
  description: 'Latest dog associated with the house',
  type: Dog,
})
async getLatestDog(
  @Param() params: GetHouseLatestDogParamsDTO,
  @Query() query: GetHouseLatestDogQueryDTO
) {
    const response = await this.houseService.getLatestDog
      params.houseId,
      query.dogBreedId,
      params.accountId
    );
    return response;
}

[pick7]

Orval is not deciding this only from the generated name. It mostly follows the shape of the OpenAPI document it receives.

In your example there are three different things:

• @ApiResponse({ type: Dog }) usually becomes a reusable component schema such as #/components/schemas/Dog, so Orval puts it in the normal schemas area.
• Individual @ApiParam(...) path params are OpenAPI parameters, not a DTO schema reference. Orval can generate them as function arguments or inline parameter handling instead of creating a separate operation schema file.
• Query parameters are often grouped into one params type for the operation, so you see an operation-specific {operationName}Params style schema/type.

So the inconsistency is probably coming from the emitted OpenAPI spec rather than Orval looking at NestJS decorators directly. The quickest way to confirm is to inspect the generated JSON/YAML:

paths:
  /...:
    get:
      parameters:
        - in: path
          name: accountId
        - in: path
          name: houseId
        - in: query
          name: dogBreedId
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dog'

If the params DTOs are not present under components.schemas, Orval has no reusable GetHouseLatestDogParamsDTO / GetHouseLatestDogQueryDTO schema to place in your schema folder.

For more predictable output, make the OpenAPI source explicit:

1. Use consistent parameter names. Your decorator uses houseId, but the route path is /:house-id; those should match as OpenAPI path params.
2. If you want reusable schemas, make sure Nest Swagger emits actual component schemas for those DTOs, not just individual @ApiParam / @ApiQuery entries.
3. If operation-specific params are acceptable, treat query/path params as operation types and keep reusable schemas for real request/response bodies.

In short: response DTOs commonly become shared schemas; path/query parameters commonly remain operation-level unless the OpenAPI document references a reusable component for them.