In this article, I'll explain how to generate an API blueprint instantly using SwagGo in Golang. API blueprint is a document that contains a bunch of API endpoints, it's slightly the same as documentation but with less description. It allows another programmer to read and see all the available endpoint and try it out with sandbox feature. Swagger is one of the most used API blueprints right now, it's available in free but limited usage. if you wanna use the free credit, you need to understand YAML notation, you can read the example notation in Swagger official documentation. But again, it's really hard and takes an expensive time to arranges all the notation to achieve a good API blueprint. Fortunately, there are tools in Golang that allow us to generate the YAML notation and automatically generate the blueprint page with only using markup notation, and it's FREE unlimited for self-host, insane right? SwagGo tools are available , the documentation is very clear, but in my experience, I need a lot of time to totally understand how to use it. here I wanna explain what I got and what I have been implemented. here These tools support familiar frameworks, such as and but in this tutorial, I would like to use default standard Go web server. echo gin, Prerequisites macOS Big Sur Shell Zsh Golang Version 1.14 http-swagger You can also use Linux, but if you are using windows, it might be has a different result and experience. first thing first, you need to install SwagGo Generator. $ go get -u github.com/swaggo/swag/cmd/swag after installation success, check the availability by using bellow command $ swag --version swag version v1 .6 .7 then, move to your project, in my example, I will make a simple project that contains several files. in order to use these tools, you need files at least main.go run command to initiate SwagGo files in your root project. $ swag init / / : : Generate swagger docs.... / / : : Generate general API Info, search dir:./ / / : : create docs.go at docs/docs.go / / : : create swagger.json at docs/swagger.json / / : : create swagger.yaml at docs/swagger.yaml 2021 02 02 22 52 14 2021 02 02 22 52 14 2021 02 02 22 52 14 2021 02 02 22 52 14 2021 02 02 22 52 14 right now, your project will contain newly added swagger files and folders. $ ls -al total drwxr-xr-x jauharibill staff Feb : . drwxr-xr-x jauharibill staff Feb : .. drwxr-xr-x jauharibill staff Feb : docs -rw-r--r-- jauharibill staff Feb : main.go 8 4 128 2 22 52 56 1792 2 22 47 5 160 2 22 52 1 80 2 22 52 in docs folder contains these files. $ cd docs $ ls -al total drwxr-xr-x jauharibill staff Feb : . drwxr-xr-x jauharibill staff Feb : .. -rw-r--r-- jauharibill staff Feb : docs.go -rw-r--r-- jauharibill staff Feb : swagger.json -rw-r--r-- jauharibill staff Feb : swagger.yaml 24 5 160 2 22 52 4 128 2 22 52 1 1397 2 22 52 1 84 2 22 52 1 45 2 22 52 there are that used to renew and generate the following and file. you don't need to modify these file, just ignore it and they will changes when you run the swag command. I will explain it below. docs.go swagger.json YAML after knowing directory structure, then we will write minimalis code like below. in main.go write these code : main ( _ httpSwagger ) { http.ListenAndServe( , router()) } { r := chi.NewRouter() r.Get( , HelloWorld) r } response { Message Status } { response response response.Message = response.Status = payload, _ := json.Marshal(response) w.Write(payload) } package import "encoding/json" "net/http" "github.com/go-chi/chi" "GOLANG-API-BLUEPRINT/docs" "github.com/swaggo/http-swagger" // main func main () ":8080" // router . func router () http Handler "/" return // default response type struct string `json:"message"` bool `json:"status"` // HelloWorld Controller func HelloWorld (w http.ResponseWriter, r *http.Request) var "Success Retrieve Data" true above code is a simple webserver build with golang, it will represent REST API. first thing first, we will try to put identity for our REST API. Put markup comment that already define by SwagGo above main method. { http.ListenAndServe( , router()) } // @title EXAMPLE REST API // @version 1.0 // @description This is a sample server celler server. // @termsOfService http://localhost:8080/terms/ // @contact.name Bill Tanthowi Jauhari // @contact.url http://localhost:8080/support // @contact.email bill@localhost // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host localhost:8080 // @BasePath / // @query.collection.format multi func main () ":8080" Run command swag to generate markup docs into yaml and json Swagger. 2021/02/03 20:58:36 Generate swagger docs.... 2021/02/03 20:58:36 Generate general API Info, search dir:./ 2021/02/03 20:58:36 create docs.go at docs/docs.go 2021/02/03 20:58:36 create swagger.json at docs/swagger.json 2021/02/03 20:58:36 create swagger.yaml at docs/swagger.yaml $ swag init -g main.go above command will update json and yaml files in docs folder. if you want to see the result, you can put that generated notation into swagger hub. you can also self host your blueprint, simply add swagger router. { r := chi.NewRouter() r.Get( , HelloWorld) r.Get( , httpSwagger.Handler( httpSwagger.URL( ), )) r } // router . func router () http Handler "/" // swagger self host router "/swagger/*" "http://localhost:8080/swagger/doc.json" return after adding swagger router, you can see the blueprint at http://localhost:8080/swagger/index.html cool, the first markup swagger that we write before already published. but the thing is there is no endpoint available yet. to put endpoint blueprint, you can put more markup into targeted method, for example : { response response response.Message = response.Status = payload, _ := json.Marshal(response) w.Write(payload) } // GET Hello World Message // @tags Message // @Summary show message hello world // @Description show message hello world // @Accept json // @Produce json // @Success 200 {object} response // @Failure 400 {object} response // @Failure 500 {object} response // @Router / [get] func HelloWorld (w http.ResponseWriter, r *http.Request) var "Success Retrieve Data" true Run swag command again, then you can see the result. finally the endpoint blueprint available, inside the endpoint there is a description and a lot of REST API information. also the best part is, you can try the endpoint directly from that page, klik "try it out" button and execute the endpoint. Finally, we already make a REST API blueprint using SwagGo. you can modify and improve all the markup by learning deeper from the documentation . Reach me out at my social media, Good luck! here Also published on: https://www.bill.web.id/2020/09/automatic-api-documentation-swagger-in.html
