Documenting POST and PUT Endpoints with JSDoc and Reusable Schemas

Introduction

In the previous lessons, you successfully documented your API's GET endpoints. You learned how to define path parameters for retrieving a single item and how to list multiple response codes (200, 400, 404). Those endpoints are for reading data.

Now, we'll focus on endpoints that write data: POST for creating new resources and PUT for updating existing ones. The key new concept for your exam is documenting the requestBody—the JSON payload a client must send. You will learn to define this body and link it to the reusable Product schema you already created, ensuring your documentation is efficient and consistent.

By the end of this lesson, you will have the complete documentation for creating and updating products, a major step toward a fully documented API.

Documenting the POST Endpoint

When a client creates a new product, they send its details (like name, price, description) in the body of a POST request. To document this, we use the requestBody keyword in our JSDoc comment. This tells Swagger that the endpoint expects a data payload.

A requestBody definition has a few key parts:

required: true: Specifies that the client must provide a body.
content: A container for different content types.
application/json: The data format we expect.
schema: Describes the structure of the JSON object. Here, we'll use $ref to point to our existing Product schema, saving us from rewriting it.

The following video section clearly demonstrates how to document a POST request, focusing specifically on defining the requestBody.

NodeJS Swagger API Documentation Tutorial Using Swagger JSDoc

The video 'NodeJS Swagger API Documentation Tutorial' by Maksim Ivanov provides a perfect walkthrough for documenting a POST request. Pay close attention to how the requestBody is structured and how it references the reusable schema.

Watch from 00:20:37 to 00:23:03. Focus on: The requestBody block and its properties (required, content). How the schema uses $ref to point to #/components/schemas/Book. The definition of success and error responses.

Your Turn: Implement the POST Documentation

Now, apply what you've learned to your productRoutes.js file. The JSDoc block below is tailored for your POST /api/products endpoint.

Important Note: The video uses status code 200 for creation, but the correct and standard code for successfully creating a resource is 201 Created. Your exam will expect 201, so we will use that.

Place this JSDoc comment directly above your POST route handler (e.g., router.post('/', ...)).

/**
 * @swagger
 * /api/products:
 *   post:
 *     summary: Create a new product
 *     tags: [Products]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/Product'
 *     responses:
 *       201:
 *         description: The product was successfully created.
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Product'
 *       400:
 *         description: Bad request. Missing required fields.
 *       500:
 *         description: Some server error
 */

Documenting the PUT Endpoint

Documenting a PUT request combines what you learned in the last lesson with what you just did for POST. A PUT request needs two things:

A path parameter (id) to identify which product to update.
A request body (requestBody) containing the new data for the product.

Your JSDoc will therefore include both a parameters section and a requestBody section.

Let's watch the next segment of the same video, which covers documenting a PUT endpoint.

NodeJS Swagger API Documentation Tutorial Using Swagger JSDoc

This next section from Maksim Ivanov's tutorial demonstrates how to document a PUT request, combining path parameters and a request body.

Watch from 00:23:09 to 00:25:23. Notice how the documentation includes both: The parameters section for the id (just like your GET-by-ID endpoint). The requestBody section for the update payload. Multiple responses for success (200), not found (404), and server error (500).

Your Turn: Implement the PUT Documentation

Now, add the documentation for your PUT /api/products/{id} endpoint. This JSDoc block includes the parameter for the id and the request body for the updated product data.

Place this JSDoc comment directly above your PUT route handler (e.g., router.put('/:id', ...)).

/**
 * @swagger
 * /api/products/{id}:
 *   put:
 *     summary: Update a product by its ID
 *     tags: [Products]
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: The ID of the product to update.
 *         schema:
 *           type: string
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/Product'
 *     responses:
 *       200:
 *         description: The product was updated successfully.
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Product'
 *       400:
 *         description: Bad request. Invalid ID or validation error.
 *       404:
 *         description: The product was not found.
 *       500:
 *         description: Some server error
 */

Verify Your Work

After adding both JSDoc blocks to your routes file:

Restart your server to regenerate the Swagger specification.
Refresh your Swagger UI page (http://localhost:PORT/api-docs).

You should now see the POST and PUT endpoints listed under the "Products" tag. Expand them to verify:

Both endpoints have a "Request body" section.
The request body shows a schema and an example based on your Product model.
The PUT endpoint also has a "Parameters" section for the id.
The "Responses" section for each endpoint lists all the status codes you defined (201, 200, 400, 404, 500).

If an endpoint is missing or the UI shows an error, the most common cause is a YAML indentation error. Each level must be indented with exactly two spaces. The articles "Documenting your Express API with Swagger" and "How to Create Swagger Documentation for Node.js APIs" both provide excellent textual examples of these structures if you need to double-check your syntax.

Conclusion

You have now documented the core "write" operations of your API. This is a critical skill for the exam, as any CRUD API task will involve documenting how clients should create and update data.

Key Takeaways:

Use the requestBody keyword to document endpoints that accept data, like POST and PUT.
Inside requestBody, define the content type (application/json) and use $ref to link to your reusable schema. This saves time and ensures consistency.
Remember to use the correct HTTP status codes: 201 Created for successful creation and 200 OK for successful updates.
Documentation for a PUT endpoint combines a parameters section (for the ID) and a requestBody section (for the data).

Next Up:

We will complete our CRUD documentation by tackling the DELETE endpoint. This is generally simpler as it often doesn't require a request body, but it's essential for a complete API specification.

Recommended resources