Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow responses description override #55

Open
programatix opened this issue Jun 8, 2024 · 1 comment
Open

Allow responses description override #55

programatix opened this issue Jun 8, 2024 · 1 comment
Assignees

Comments

@programatix
Copy link

Is your feature request related to a problem? Please describe.
Currently, the JSDoc comments on the response type is used as description. However, it may not accurately represent the actual response description.

Example,
image

Describe the solution you'd like
It would be great if the description can be overwritten with local JDDoc ccomments.

Exxample,

delete: {
    summary: "Delete a task",
    description: "Delete a specific task by ID.",
    path: {
        /** The identifier of the task to delete */
        id: number
    },
    responses: {
        /** Task deleted */
        204: "",
        /** Invalid params */
        400: ProblemDetails
        /** Task not found */
        404: ProblemDetails
    }
}

For the example above, status 204 description is inserted correctly as seen in the screenshot above.

@programatix
Copy link
Author

It turns out that the descriptions are added but to the wrong location. It should be placed in the location as indicated in the arrows in the screenshot below.
image

Also, the schema under components already has its own description, thus does not need to be repeated.
image

In addition to that, swagger editor produces warning when description is included together with $ref.
image

@hyeonss0417 hyeonss0417 self-assigned this Jun 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants