2022-12-09
1989
#node
Diogo Souza
24092
Dec 9, 2022 â‹… 7 min read

Documenting your Express API with Swagger

Diogo Souza Brazilian dev. Creator of altaluna.com.br

Recent posts:

8 best Go web frameworks for 2025

The 8 best Go web frameworks for 2025: Updated list

Looking for the best Go frameworks? Compare the top 8 Go web frameworks for 2025, including Gin, Fiber, Echo, and Beego, with pros, cons, and performance insights.

Victor Jonah
Apr 3, 2025 â‹… 15 min read
Making Your First Game In Excalibur.js

Game development for frontend: Building with Excalibur.js

Build your first 2D browser game using JavaScript and the Excalibur.js library, covering essential game development concepts.

Yashodhan Joshi
Apr 3, 2025 â‹… 25 min read
angular vs react

Angular vs. React: Which one should you choose?

Explore the key differences between Angular and React, their strengths, and use cases to help developers decide which option to choose.

Oscar Jite-Orimiono
Apr 2, 2025 â‹… 5 min read
axios in javascript

Axios in JavaScript: How to make GET, POST, PUT and DELETE requests

Learn how to use Axios in JavaScript for GET, POST, PUT & DELETE requests. Examine setup, error handling, and API best practices.

Faraz Kelhini
Apr 1, 2025 â‹… 19 min read
View all posts

11 Replies to "Documenting your Express API with Swagger"

  1. Ben – I have tried to add yaml version of Book/Books Schema in book.js file but getting error in yaml parsing. Would it be possible for you to share book.js final version in with jsdocs code is available. Marry Christmas.

  2. These Comment blocks don’t work for me. I’m using typescript but my files wont compile with this sort of comment syntax

  3. Thank you Ben, great article

    but I have yaml errors

    Not all input has been taken into account at your final specification.
    Here’s the report:

    YAMLSemanticError: Map keys must be unique; “type” is repeated at line 1, column 1:

    components:
    ^^^^^^^^^^^…

    YAMLSemanticError: Map keys must be unique; “type” is repeated at line 1, column 1:

    components:
    ^^^^^^^^^^^…

    YAMLSemanticError: Map keys must be unique; “description” is repeated at line 1, column 1:

    components:
    ^^^^^^^^^^^…

    YAMLSemanticError: Map keys must be unique; “title” is repeated at line 1, column 1:

    components:
    ^^^^^^^^^^^…

    YAMLSemanticError: Map keys must be unique; “type” is repeated at line 1, column 1:

    components:
    ^^^^^^^^^^^…

    YAMLSemanticError: Map keys must be unique; “description” is repeated at line 1, column 1:

    components:
    …………………………

    Can you please share the full routes/books.js ?

    Thank you

  4. The code in this article don’t work for me, but here is working for me.
    Why don’t you try this?

    “`
    /**
    * @openapi
    * tags:
    * name: Books
    * description: API to manage your books.
    */
    “`

    “comment out with ‘/’ and ‘*’ ” and “@openapi” are keys for working in your app.
    if you made setting as below,

    “`
    const options = {
    definition: {
    swagger: …
    “`

    you can use @swagger on the top of your swagger jsdoc.
    Thanks

  5. put this text at front of books.js
    then works
    note you must write “paths”… in the example it was just “path”

    /**
    * @swagger
    * tags:
    * name: Books
    * description: API to manage your books.
    * paths:
    * /books/:
    * get:
    * summary: Lists all the books
    * tags: [Books]
    * responses:
    * “200”:
    * description: The list of books.
    * content:
    * application/json:
    * schema:
    * $ref: ‘#/components/schemas/Book’
    * post:
    * summary: Creates a new book
    * tags: [Books]
    * requestBody:
    * required: true
    * content:
    * application/json:
    * schema:
    * $ref: ‘#/components/schemas/Book’
    * responses:
    * “200”:
    * description: The created book.
    * content:
    * application/json:
    * schema:
    * $ref: ‘#/components/schemas/Book’
    * /books/{id}:
    * get:
    * summary: Gets a book by id
    * tags: [Books]
    * parameters:
    * – in: path
    * name: id
    * schema:
    * type: integer
    * required: true
    * description: The book id
    * responses:
    * “200”:
    * description: The list of books.
    * content:
    * application/json:
    * schema:
    * $ref: ‘#/components/schemas/Book’
    * “404”:
    * description: Book not found.
    * put:
    * summary: Updates a book
    * tags: [Books]
    * parameters:
    * – in: path
    * name: id
    * schema:
    * type: integer
    * required: true
    * description: The book id
    * requestBody:
    * required: true
    * content:
    * application/json:
    * schema:
    * $ref: ‘#/components/schemas/Book’
    * responses:
    * “204”:
    * description: Update was successful.
    * “404”:
    * description: Book not found.
    * delete:
    * summary: Deletes a book by id
    * tags: [Books]
    * parameters:
    * – in: path
    * name: id
    * schema:
    * type: integer
    * required: true
    * description: The book id
    * responses:
    * “204”:
    * description: Delete was successful.
    * “404”:
    * description: Book not found.
    * components:
    * schemas:
    * Book:
    * type: object
    * required:
    * – title
    * – author
    * – finished
    * properties:
    * id:
    * type: integer
    * description: The auto-generated id of the book.
    * title:
    * type: string
    * description: The title of your book.
    * author:
    * type: string
    * description: Who wrote the book?
    * finished:
    * type: boolean
    * description: Have you finished reading it?
    * createdAt:
    * type: string
    * format: date
    * description: The date of the record creation.
    * example:
    * title: The Pragmatic Programmer
    * author: Andy Hunt / Dave Thomas
    * finished: true
    */

  6. ps: i forgot , you also have to chagne in server.js

    url: “http://localhost:3000/books”,

    to
    url: “http://localhost:3000”,

  7. Big big thanks team LogRocket and author, this sample is good for practise and learn, btw i checked and pushed to Github this source, if you want to test, welcome github.com/vinhhung263/express-api-with-swagger

  8. For the ones that get the following error:
    “Unable to render this definition
    The provided definition does not specify a valid version field.
    Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: “2.0” and those that match openapi: 3.0.n (for example, openapi: 3.0.0).”

    Please add the swagger version as the following:

    definition: {
    openapi: ‘3.1.0’,
    swagger: ‘2.0’,
    ….all the rest.

Leave a Reply