Search code examples
javascriptnode.jsyamlswagger

API documentation using swagger, YAML syntax error

I am learning API documentation using swagger (open API version 3)

I am trying to document the post route.

Here is my YAML syntax.

/**
 * @swagger
 * /home: 
 *  post:
 *      summary: create a new product
 *      tags: [Products]
 *      requestBody:
 *          required: true
 *          content:
 *              application/json:
 *                  schema:                 
 *                      $ref: "#/components/schemas/Product"
 * 
 *      responses:
 *          200:
 *              description: The product was inserted successfully
 *              content:
 *                  application/json:
 *                      schema:
 *                          $ref: "#/components/schemas/Product"
 *         500:
 *              description: Some server error
 * 
 */

I have thoroughly gone through this code. Yet, I keep running into this error:

Here's the report:


 Error in ./routes/route.js :
YAMLSyntaxError: All collection items must start at the same column at line 3, column 6:

     summary: create a new product
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^…
Solution

  • First of all, I strongly recommend using this Swagger Editor. Using it you may find that you are just missing indent(s) before 500: in responses:

    enter image description here

    Changing the script to something like this should solve your issue:

        responses:
        200:
            description: The product was inserted successfully
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/Product"
        500:
            description: Some server error