scottie1984 / swagger-ui-express

Adds middleware to your express app to serve the Swagger UI bound to your Swagger document. This acts as living documentation for your API hosted from within your app.
MIT License
1.4k stars 225 forks source link

Route params not filling successfully in nested api controller files using "mergeParams: true" #371

Open PaulBitplex opened 2 months ago

PaulBitplex commented 2 months ago

I am implementing Swagger into an ExpressJs project and there is aparticular nessted route that is not filling dynamic route params at all and the request is being sent through like: http://localhost:4900/v2/mines/455/positionpermissions/position/%7BpositionId%7D/group/%7BroleId%7D

This controller is successfully working in a production application and the controller is successfully filling these params both in requests from the front end project and also hitting the api directly in Postman, both returning a successful 200 response. I have checked my JsDocs to ensure naming is uniform across the controller and the jsdoc.

Swagger-ui-express v5.0.0 swagger-jsdoc v6.2.8 ExpressJs v4.16

we are using const router = express.Router({ mergeParams: true }); in the parent controller file. Could this be a problem with how Swagger uses this?

Here is my jsdoc code:

  @swagger
  /v2/mines/{mineId}/positionpermissions/position/{positionId}/group/{roleId}:
    post:
      summary: Assign a role to a position within a specific mine
      description: |
        Assigns a specified role to a position within a mine. This action requires the user to have the permission to add groups within the mine context.

        Permissions Required
        - `MinePermissions.ADD_GROUP`
      tags:
        - Mines/PositionPermissions
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: mineId
          required: true
          schema:
            type: string
          description: The unique identifier of the mine.
        - in: path
          name: positionId
          required: true
          schema:
            type: string
          description: The unique identifier of the position within the mine.
        - in: path
          name: roleId
          required: true
          schema:
            type: string
          description: The unique identifier of the role to assign to the position.
      responses:
        200:
          description: Role successfully assigned to the position.
        400:
          description: Bad request, due to missing or invalid parameters.
        403:
          description: Forbidden, the user does not have the required permissions to assign roles.
        500:
          description: Internal server error due to a problem with the server.

And here is the controller code, listed in the same folder.

router.post('/position/:positionId/group/:roleId', async function (req, res) {
    // @ts-ignore mineId is defined in mines/index.js and get the value by mergeParams within router
    const mineId = req.params.mineId;
    const positionId = req.params.positionId;
    const roleId = req.params.roleId;
    const userId = req.customUser.id;

    // rest of controller code here
});

I have a GET request in this same file that does not use the extra parameters, and it is working fine, so I am confident the import in my app.js is fine