In Go, you can write comments in code either as single-line or multi-line comments.

package main

// one line comment
func main() {
    /*
        multiline
        comment
    */
}

Comments are usually explanations about the code, written for programmers. In Go, there are some special comment directives that enable certain features in the Go command-line tool. One of these directives is go:generate, which lets you write a command-line instruction inside your code as a comment, and then run it using the go generate command.

package main

import "log"

//go:generate echo "This is a message from go generate"
func main() {
    log.Println("Hello world!")
}

In the code above, we started our comment with go:generate and then added an echo command. If we run the go generate command in the folder containing the file above, the text This is a message from generate is printed to the screen.

In general, go:generate makes it possible to define, directly inside the source code, a set of commands needed to automate tasks such as generating code, building helper files, or running third-party tools. These commands are placed in the code as special comments, and then, by running the go generate command on the command line, they're all executed together.

This way, the processes tied to the code are documented and maintained alongside that same code, and their dependencies become clearer. In fact, what go generate does isn't inherently different from tools like Make or Taskfile, and the same operations could be implemented with them as well. But the key advantage of go generate is that it's part of Go's official tooling; so wherever Go is installed, the go command is also available, and we won't need to install, configure, or add extra dependencies on third-party tools. This makes the code-generation process simpler, more portable, and more consistent with the Go ecosystem.

The go generate feature was first introduced in February 2015, along with the release of Go 1.4. Since then, this command has been an official part of the go command-line tool in every subsequent version, and it doesn't need to be installed separately.

Next, we'll use go:generate to generate openapi files for our Go code.

Generating openapi/swagger Files for Go Code

Here, we briefly explain how go:generate helps us generate openapi documentation and integrate it with our code.

To integrate with openapi, we first install the swag tool as follows: