Shown description is the response body description

[Clement-Z4RM]

Hello, thank you for your work and this tool.

Description

I tried to add swagger comments on one of my controllers' routes, but the description shown is a wrong one. With this controller:

import Cible from "#models/cible";

export default class CiblesController {
    /**
     * @index
     * @summary Get the cibles list
     * @description Lorem ipsum dolor sit amet
     * @responseBody 200 - <Cible[]> - The cibles list
     * @responseBody 401 - <Errors> - Unauthorized access
     */
    async index() {
        return Cible.query().orderBy("id", "asc");
    }
}

the description shown on the Swagger UI (and even in the JSON) is "The cibles list" - which is the status 200 response body description -, instead of "Lorem ipsum dolor sit amet":

Expected behaviour

The route's description should be "Lorem ipsum dolor sit amet", like in this following screen (edited with Chrome DevTools):

Environment information

Versions

• Node.js: 22.15.0 (LTS)
• AdonisJS: 6.17.2
• AutoSwagger: 3.72.0

[ad-on-is]

The description should come after the status

[Clement-Z4RM]

I don't really understand what do you mean?

With another controller (authentication), it works well:

import type { HttpContext } from "@adonisjs/core/http";

export default class AuthController {
    /**
     * @logout
     * @summary Déconnexion d'un utilisateur
     * @description Cette méthode permet à un utilisateur de se déconnecter. Si son jeton d'accès est valide, il sera invalidé et l'utilisateur sera déconnecté.
     * @responseBody 200 - {} - Utilisateur déconnecté
     * @responseBody 401 - <Errors> - Accès non autorisé
     */
    async logout({ auth }: HttpContext) {
        await auth.use("api").invalidateToken();
    }
}

The @description is displayed under the title, not the response body description:

[ad-on-is]

Ohhg.. sorry... I thought the description had to be right after the status... sorry, my bad for the confusion

[addamai]

Hello,

there’s a small bug: you need to double the space between statut and just before the dash in return, which should result in:

@responseBody 200  - <Cible[]> - The cibles list

[Clement-Z4RM]

Hello, yes it worked, thank you for the work-around. Hopping it'll be fixed. However, the status 200 appears after the others, like if it was considered as "200 ", so Swagger doesn't know it.

[addamai]

Hello, Normally, it follows the order of the comments: if you put it first, it will appear first; if you put it last, it will appear last. Check your console to see if there is any Swagger error.

[Clement-Z4RM]

Hello, with this code:

import Cible from "#models/cible";

export default class CiblesController {
    /**
     * @index
     * @summary Get the cibles list
     * @description Lorem ipsum
     * @responseBody 200  - <Cible[]> - The cibles list
     * @responseBody 401 - <Errors> - Unauthorized access
     */
    index() {
        return Cible.query().orderBy("id", "asc");
    }
}

The order is bad: (No error in the console)

[DeVoresyah]

Hi @Clement-Z4RM , I've published a new package to integrate Swagger/OpenAPI into your AdonisJS project easily.

More details: https://github.com/DreamsHive/open-swagger