swaggernestjs

NestJS swagger documenting path parameter


I'm having trouble using NestJS's attributes to document an embedded parameter in a URL request.

The request looks like this:

POST /api/todo-lists/{listId}/todos

The controller and the method handling the POST with swagger attributes looks like this:

@Controller('api/todo-lists')
export class TodosController {
@Post('/:listId/todos')

 @ApiQuery({
  name: 'listId',
  description: "The ID of the list associated with this todo",
  required: true,
  type: String,
})
 async create(@AuthUser() user, @CurrentToDoList() todoList, @Body() todo: TodoCreateDto): 
<removed for brevity>
 }
}

This is creating the follwing Swagger doc:

paths:
  /api/todo-lists/{listId}/todos:
    post:
      operationId: TodosController_create
      parameters:
        - name: listId
          required: true
          in: query
          description: The ID of the list associated with this todo
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TodoCreateDto'

This is causing a validation error:

Semantic error at paths./api/todo-lists/{listId}/todos
Declared path parameter "listId" needs to be defined as a path parameter at either the path or operation level

I am not using listId in the call to the controller itself, I have middleware that is grabbing the listID and instantiating the list which gets passed to every controller method.

Any ideas? I would like to add the listID documentation at the controller level but can't figure out how to do that.


Solution

  • /:listId/todos this is a segment fora URL parameter, not a Query parameter. Use @ApiParam() instead of @ApiQuery()