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:

Stagehand and Gemini logos on a gradient background symbolizing AI web automation

How to build a web-based AI agent with Stagehand and Gemini

This guide walks you through creating a web UI for an AI agent that browses, clicks, and extracts info from websites powered by Stagehand and Gemini.

Elijah Asaolu
Jul 4, 2025 â‹… 8 min read
Getting Started With Claude 4 API: A Developer's Walkthrough

Getting started with Claude 4 API: A developer’s walkthrough

This guide explores how to use Anthropic’s Claude 4 models, including Opus 4 and Sonnet 4, to build AI-powered applications.

Andrew Baisden
Jul 3, 2025 â‹… 16 min read
ai dev tool power rankings

AI dev tool power rankings & comparison [July 2025 edition]

Which AI frontend dev tool reigns supreme in July 2025? Check out our power rankings and use our interactive comparison tool to find out.

Chizaram Ken
Jul 2, 2025 â‹… 3 min read
how API client automation can save you hours in development

How API client automation can save you hours in development

Learn how OpenAPI can automate API client generation to save time, reduce bugs, and streamline how your frontend app talks to backend APIs.

Lewis Cianci
Jul 1, 2025 â‹… 7 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