Parsing of @Success and @Failure comments is buggy

[stefanMadzharov]

Describe the bug
There is something wrong with the parsing of @success and @failure particularly of their comment fields when there aren't any {param type} and data type fields. Example:
// @Failure 500 "Internal Server Error
If there are only numbers in the comment it can be arbitrarily long. Still when the comment is "Internal Server Error" swag init gives me an error saying:
ParseComment error in file placeholder/placeholder.go :can not parse response comment "500 "Internal Server Error""

Your swag version
1.7.0

Your go version
1.15.7

Desktop:

• OS: linux/amd64

[snaveen]

I am also facing this issue

[sammyne]

Same issue~

[stepotronic]

Looking at the code the format is not supported:

swag/operation.go

Line 727 in 17c1766

func (operation *Operation) ParseResponseComment(commentLine string, astFile *ast.File) error {

It needs to be 5 sections in total divided by spaces
@Failure 500 {schemaType} refType responseDescription

I would however agree that there needs to be a way to define an empty response in certain cases, too.

[belindaxinyi]

I am also facing this issue when trying to update the docs...

[ubogdan]

Hey guys, Is there anyone reading that stupid documentation?

This is an invalid definition:

// @Failure 500 "Internal Server Error"

A working example can be found here.

if you need to add a "description" about why the error is happening this can be done as the following example.

Hope that was helpful.

[j-sv]

I'm facing the same issue on responses that don't contain a response body. From the Swagger docs:

Empty Response Body
Some responses, such as 204 No Content, have no body. To indicate the response body is empty, do not specify a content for the response:

      responses:
        '204':
          description: The resource was deleted successfully.

The examples given would set a type field on the response, which wouldn't be correct.

[ubogdan]

Is anyone open to write an implementation?

[j-sv]

@ubogdan, would you accept supporting it as @Success 200 {null} null "An empty response".

[ubogdan]

I feel this definition may be more intuitive for a GO developer

@Success 200 {object} nil "An empty response".

I especially prefer nil (go like) instead of null (javascript like).

[ubogdan]

The feature was implemented and will be released in v1.7.2.