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:

what are the event loop and call stack in JavaScript

What are the event loop and call stack in JavaScript?

Learn how the call stack, event loop, and various queues help JavaScript handle asynchronous operations while maintaining its single-threaded nature.

Ikeh Akinyemi
Feb 18, 2025 â‹… 6 min read
how and when to use JavaScript arrow functions

How and when to use JavaScript arrow functions

Arrow functions have a simpler syntax than standard functions, and there are some important differences in how they behave.

Joe Attardi
Feb 17, 2025 â‹… 5 min read
javascript is null or empty function

How to check for null, undefined, or empty values in JavaScript

In most languages, we only have to cater to null. But in JavaScript, we have to cater to both null and undefined. How do we do that?

Lewis Cianci
Feb 14, 2025 â‹… 4 min read
MERN Stack: Overview With Examples

What is the MERN stack? Overview with examples

Discover how the MERN stack (MongoDB, Express.js, React, Node.js) enables developers to build dynamic, performant, modern websites and apps.

Nefe Emadamerho-Atori
Feb 13, 2025 â‹… 20 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