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:

7 TUI Libraries For Creating Interactive Terminal Apps

7 TUI libraries for creating interactive terminal apps

When writing applications, a good user interface is just as important as the actual app’s functionality. A good user interface […]

Yashodhan Joshi
Jun 14, 2024 ⋅ 18 min read
Expo Router Adoption Guide Overview Examples And Alternatives

Expo Router adoption guide: Overview, examples, and alternatives

Expo Router provides an excellent file-based routing solution with crucial features such as deep linking and native support.

Marie Starck
Jun 13, 2024 ⋅ 8 min read
Superglue Vs. Hotwire For Modern Frontend Development

Superglue vs. Hotwire for modern frontend development

Explore how Superglue and Hotwire revolutionize frontend development with HTML over the wire, enhancing performance, flexibility, and ease of use.

Frank Joseph
Jun 12, 2024 ⋅ 7 min read
Using Pocketbase To Build A Full Stack Application

Using PocketBase to build a full-stack application

PocketBase is a performant Go-based tool that comes with essential features like user auth, file uploads, access control rules, and more.

Rahul Padalkar
Jun 11, 2024 ⋅ 18 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