swag icon indicating copy to clipboard operation
swag copied to clipboard

`swag fmt` fails to format annotations correctly unless there’s a blank line before the function

Open redish101 opened this issue 5 months ago • 8 comments

Describe the bug When running swag fmt, annotations in the comment block are not indented as expected. The formatter only works correctly if there is an extra blank line after the last annotation.

To Reproduce

  1. Create a Go file with the following content (no blank line after annotations):

    // @title retalk
    // @version 1.0.0
    // @license.name	GPL 3.0
    // @license.url https://www.gnu.org/licenses/gpl-3.0.en.html
    // @securityDefinitions.apikey apiKeyAuth
    // @in header
    // @name Authorization
    func Start() {
        // ...
    }
    
  2. Run:

    swag fmt
    
  3. Observe that the formatter produces incorrect output

Image
  1. Add a blank line after the last annotation:

    // @name						Authorization
    
    func Start() {
        // ...
    }
    
  2. Run swag fmt again and notice that formatting is now correct.

Image

Expected behavior swag fmt should correctly format the annotation block and leave the function signature on its own line without requiring an extra blank line.


Your swag version v1.16.4

Your go version go version go1.24.4 linux/amd64


Desktop (please complete the following information):

  • OS: macOS and Linux
  • Terminal/Shell: bash

Additional context This issue only appears when there is no blank line between the last // @… annotation and the func.

redish101 avatar Jul 18 '25 00:07 redish101

If there is no blank line, it's docs of the below function, otherwise it's global comments. And the docs would be fmt again by the IDE or gofmt, I guess. A normal examle of function docs may be like:

// Start
//
//   @xxxx  yyyy
func Start(){
}

sdghchj avatar Jul 18 '25 03:07 sdghchj

I got the same error result by simply executing swag fmt through the terminal without opening any IDE. Copyright © Redish101. All rights reserved.

redish101 avatar Jul 18 '25 03:07 redish101

I mean swag fmt calls go fmt at end.

https://github.com/swaggo/swag/blob/master/formatter.go#L73

sdghchj avatar Jul 18 '25 04:07 sdghchj

It also adds the tabs where there should be none

Image

thommeo avatar Jul 25 '25 12:07 thommeo

+1, My code even not format by swag with the line break

buiducnhat avatar Aug 04 '25 04:08 buiducnhat

Same problem, using swaggo v2.0.0 Image

lutfiandri avatar Oct 06 '25 07:10 lutfiandri

still with error here...

bernardinorafael avatar Nov 10 '25 00:11 bernardinorafael

This is an OOS project. any contribution is wellcome. Let me know if i can assis with a PR

ubogdan avatar Nov 11 '25 09:11 ubogdan