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.
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.
packagemainimport("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")typeHealthCheckResponsestruct{Resultstring`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
funcmain(){http.HandleFunc("/v1/health-check",HealthCheckHandler)http.HandleFunc("/docs/",httpSwagger.WrapHandler)http.HandleFunc("/",RootHandler)port:=os.Getenv("PORT")ifport==""{port="8080"}log.Println("App started on http://localhost:"+port)iferr:=http.ListenAndServe(":"+port,nil);err!=nil{panic(err)}}funcRootHandler(whttp.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]
funcHealthCheckHandler(whttp.ResponseWriter,r*http.Request){varhcHealthCheckResponsehc.Result="ok"json.NewEncoder(w).Encode(hc)}
Edd is a PHP and Go developer who enjoys blogging about his experiences, mostly about creating and coding new things he's working on and is a big beliver in open-source and Linux.
Install Latest Version of Go (Linux/OSX)
–
This article describes how to install the latest version of Go (golang). It also helpfully updates itself by pulling the latest version numbers directly, so you don’t have to go and dig out the latest version each time they release a version (yay!) - just copy and paste away. For more info, try their installer docs.