Swaggo with Fiber in Golang
Swagger API Documentation with Swaggo in Golang
In the last blog post, we talked about how we can create endpoints with the Fiber library. In this blog post, we will look at how we can integrate the Swagger into our Fiber endpoints with the Swaggo library.
Note: You can get the full source code from here.
If you prefer to watch the video version of this blog post, here it is.
If you don’t know what Swagger is, it is a UI that allows you to visualize and interact with the API’s resources. It is probably the most popular API documentation tool in the software world. Here is a demo.
Swaggo is a library where you can generate swagger documentation with annotations. It can work with many web frameworks like Fiber and Gin.
To start, let’s first download the Swaggo library.
go get -u github.com/swaggo/swag/cmd/swag
Now, we can run the swag init
command in the Go project root folder, which contains main.go
file.
Now you can see that there is a generated folder called docs, and there are files under it: docs.go, swagger.json, and swagger.yml. These are generated files with our annotations.
Now, we can download the Fiber Swaggo library.
go get -u github.com/gofiber/swagger
In order to make your Swagger doc work, you need to import Fiber Swagger and docs folder in main.go
.
import (
"github.com/gofiber/swagger"
_ "yt-swagger-go/docs"
)
Looks like we are ready. First, let’s put our API name in the documentation by adding annotations to our main function in main.go
and add our swagger endpoint to see in the browser.
And now we can generate our swagger doc with swag init
and swag fmt
. swag fmt
Checks spaces, etc. It is an optional command, and I just like to use it :)
Now, let’s run our project and go to localhost:3000/swagger/index.html
endpoint.
And we can see our main doc headers in Swagger! Great!
Now, let’s start to document our endpoints. We have one GET and one POST endpoint. We can start with the GET endpoint.
Document GET Endpoint
Our endpoint is like this
func GetOrderByCode(app *fiber.App) fiber.Router {
return app.Get("/orders/code/:orderCode", func(ctx *fiber.Ctx) error {
fmt.Printf("Your correlationId is %v", ctx.Locals("correlationId"))
return ctx.SendString("This is your order Code: " + ctx.Params("orderCode"))
})
}
This endpoint gets orderCode
from the path, controls correlationId
which we have a middleware that controls if it is null or not, and returns orderCode
within a string. The annotations can be like this.
// GetOrderByCode Getting Order by Code
//
// @Summary Getting Order by Code
// @Description Getting Order by Code in detail
// @Tags Orders
// @Accept json
// @Produce json
// @Param x-correlationid header string true "code of Order"
// @Param orderCode path string true "code of Order"
// @Success 200 {string} string
// @Router /orders/code/{orderCode} [get]
func GetOrderByCode(app *fiber.App) fiber.Router {
return app.Get("/orders/code/:orderCode", func(ctx *fiber.Ctx) error {
fmt.Printf("Your correlationId is %v", ctx.Locals("correlationId"))
return ctx.SendString("This is your order Code: " + ctx.Params("orderCode"))
})
}
Summary: Summary :)
Description: Detailed explanation of what this endpoint does.
Tags: How to group in swagger endpoints. I will talk about this later as well.
Accept: Accept request type
Product: Return request type
Param: This annotation gets more than one parameter. It is like this: param name, param type, data type, isMandatory, description(optional).
Success: Successful return status code and type
Router: URL and endpoint type (get, post, delete, etc.)
This is it for our first endpoint. Let’s generate our swagger with swag init
, and see the result in the browser.
Great, we can see our endpoint! Let’s go to our POST endpoint.
Document POST Endpoint
First, let’s see what the endpoint looks like.
func CreateOrder(app *fiber.App, customValidator *validation.CustomValidator) fiber.Router {
return app.Post("/orders", func(ctx *fiber.Ctx) error {
var request model.CreateOrderRequest
err := ctx.BodyParser(&request)
if err != nil {
return err
}
if errs := customValidator.Validate(customValidator.Validator, request); len(errs) > 0 && errs[0].HasError {
errorMessages := make([]string, 0)
for _, err2 := range errs {
errorMessages = append(errorMessages, fmt.Sprintf("%s field has failed. Validation is: %s", err2.Field, err2.Tag))
}
return ctx.Status(fiber.StatusBadRequest).JSON(strings.Join(errorMessages, " and that "))
}
return ctx.Status(fiber.StatusCreated).JSON("Order created successfully!")
})
}
What this endpoint does? It is a POST endpoint, it gets a request from the body called CreateOrderRequest
, parse it, validate the request, and if validation fails, returns BadRequest
. If everything is good, return Created
with a string
.
Annotations would be like this.
// CreateOrder Creating Order
//
// @Summary Creating Order
// @Description Creating Order with given request
// @Tags Orders
// @Accept json
// @Produce json
// @Param x-correlationid header string true "code of Order"
// @Param request body model.CreateOrderRequest true "Request of Creating Order Object"
// @Success 200 {string} string
// @Failure 400 {string} string "Bad Request"
// @Router /orders [post]
func CreateOrder(app *fiber.App, customValidator *validation.CustomValidator) fiber.Router {
// I am not showing here for keep the code snippet short.
}
Our Tag is still Orders, so it could be grouped with our GET endpoint. We have little new details in the annotations; let’s look at them.
Param body
: Now we are getting the request from the body
and it is a custom struct
, which we can write like package.StructName
.
Failure: Fail return status code and type. (You didn’t see that coming, right? :D)
Not let’s run swag init
and see our documentation.
We have two order endpoints under the same group, thanks to Tags
annotation. Let's open our POST endpoint.
We can see header
, our CreateOrderRequest
object, and possible responses. Cool!
Document Request Object
Sometimes, we can have complex request objects and want to explain further by property. We can do this with Swaggo. Let’s try this on our CreateOrderRequest
object.
// CreateOrderRequest
// @Description Request about creating Order
type CreateOrderRequest struct {
// shipment no of Order
ShipmentNumber string `json:"shipmentNumber" validate:"required"`
// country code like: tr, us
CountryCode string `json:"countryCode" validate:"required,len=2"`
// age to make sure you are young
Age int `json:"age" validate:"required,oldAge"`
}
And here’s the result of this. First swag init
, then run the project again.
There are a lot of annotations in Swaggo, and you can enrich the documentation of your APIs as much as you want.
Thanks for reading.
May the force be with you!
Originally published at https://firatkomurcu.com on February 6, 2024.