Add Swagger Docs to a Go API

Swagger allows developers to easily create api documentation which is defined using comments in the code and then generated as a yaml config file.

Using tools like Swagger has many advantages, like allowing you to generate these automatically (saving you time) and that it keeps your code and documentation as close as possible (in distance terms). The idea being that if the docs are hard to update and far away, you just won’t.

You can define things is shown below:

1
// @title        My API documentation

1. Grab the packages you need

We use the http-swagger package, which provides us with some middleware for showing the docs in our app.

1
go get "github.com/swaggo/http-swagger"

2. Install Swag (cmd swagger generator)

We’ll also need the Swag tool to read our comments and generate the swag definition file.

View On Github (with install instructions)

3. View our example code

Put it all together and we have our code below. This is in it’s “full version” - but shows us a complete working example. The important bits add adding _ "swaggerexample/docs" and making a new router endpoint.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
package main

import (
	"encoding/json"
	"log"
	"net/http"
	"os"

	// Super important: import the docs into project
	// we used "swaggerexample" as that was our project name, use your own.
	_ "swaggerexample/docs"

	// Import the swagger docs middleware
	httpSwagger "github.com/swaggo/http-swagger"
)

type HealthCheckResponse struct {
	Result string `json:"result" example:"ok"`
}

// @title        My API documentation
// @version      0.1
// @description  A collection of fun related api endpoints.
// termsOfService  http://swagger.io/terms/
// @x-logo       {"url": "https://example.com/img.png", "backgroundColor": "#000000", "altText": "example logo", "href": "https://example.com/img.png"}

// contact.name   API Support
// @contact.url   https://gophercoding.com
// contact.email  support@gophercoding.com

// @host                        api.gophercoding.com
// @securityDefinitions.apikey  ApiKeyAuth
// @in                          header
// @name                        Authorization

func main() {

	http.HandleFunc("/v1/health-check", HealthCheckHandler)
	http.HandleFunc("/docs/", httpSwagger.WrapHandler)
	http.HandleFunc("/", RootHandler)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}

	log.Println("App started on http://localhost:" + port)
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		panic(err)
	}
}

func RootHandler(w http.ResponseWriter, r *http.Request) {
	http.Redirect(w, r, "/docs/", http.StatusTemporaryRedirect)
}

// HealthCheckHandler shows if the api is running
// @Summary      Health Check
// @Description  check api is running
// @Accept       json
// @Produce      json
// @Tags         Tools
// @Security     ApiKeyAuth
// @Success      200  {object}  HealthCheckResponse
// @Router       /v1/health-check [get]
func HealthCheckHandler(w http.ResponseWriter, r *http.Request) {
	var hc HealthCheckResponse
	hc.Result = "ok"
	json.NewEncoder(w).Encode(hc)
}

Example In Action

generate swagger api docs in golang

Add Swagger Docs to a Go API

1. Grab the packages you need

2. Install Swag (cmd swagger generator)

3. View our example code

Example In Action

Related Posts