Working with OpenAPI (Swagger) – Auto‑generate Docs

OpenAPI with swaggo

This lesson explains the main concept clearly with beginner-friendly examples and background so you can learn why the code works.

Install the generator:

$ go install github.com/swaggo/swag/cmd/swag@latest
$ go get -u github.com/swaggo/http-swagger

Add annotations to handlers:

// @Summary Create a Todo
// @Description Add a new todo item
// @Accept json
// @Produce json
// @Param todo body Todo true "Todo item"
// @Success 201 {object} Todo
// @Router /todos [post]
func createTodo(w http.ResponseWriter, r *http.Request) { /* … */ }

Generate docs:

$ swag init -g main.go

The command creates docs/swagger.json and docs/swagger.yaml.

Serve the UI:

http.Handle("/swagger/", httpSwagger.Handler())

Visit http://localhost:8080/swagger/index.html.