Made withGinClip

Swagger API Documentation with Swaggo in Golang

B

Ben MFK

Creator on the Gin channel

Watch on YouTube ↗

15K viewsJan 31, 202413:01 runtime

Learn how to automatically generate interactive Swagger API documentation for your Golang applications using the Swaggo library. This step-by-step guide demonstrates integrating Swaggo with a Fiber web framework project. You'll see how to use Go annotations to define API…

Chapters

#gin#clip#backend

Core Concept: Declarative API Documentation

Swaggo generates rich, interactive Swagger/OpenAPI documentation by parsing annotations written directly in your Go source code. This approach keeps your API documentation in sync with the code it describes.

Getting Started with Swaggo

Install the Swaggo CLI:

go install github.com/swaggo/swag/cmd/swag@latest

Install the Framework-Specific Wrapper: For Fiber, you need fiber-swagger.
```
go get github.com/swaggo/fiber-swagger
```
Generate Documentation: The swag init command parses your annotations and creates a docs directory containing the necessary swagger.json, swagger.yaml, and docs.go files.

Important
You must run swag init every time you add or modify annotations to regenerate the documentation files. Otherwise, your changes will not appear in the UI.

Configuration and Setup

Main API Information: Add a comment block with annotations above your main() function to define global details like the API title, description, and version.

Register the Handler: Expose the Swagger UI by registering the handler with your Fiber application.

import fiberSwagger "github.com/swaggo/fiber-swagger"
// ...
app.Get("/swagger/*", fiberSwagger.WrapHandler)

Documenting Endpoints and Models

Use annotation blocks above each handler function to define its behavior.

Key Endpoint Annotations:
- @Summary: A short, one-line description.
- @Description: A more detailed explanation of the endpoint.
- @Tags: A comma-separated list to group related endpoints (e.g., Orders).
- @Router: Defines the URL path and HTTP method (e.g., @Router /orders/{code} [get]).
- @Param: Describes a single parameter.
  - Syntax: @Param {name} {location} {type} {required} "Description"
  - location: Can be path, header, query, or body.
- @Success: Describes a successful response (@Success 200 {object} string).
- @Failure: Describes a potential error response (@Failure 400 {object} string).
Documenting Models:
- To add descriptions for the fields within a request or response struct, simply add a standard Go comment directly above each field.

Tip
Use swag fmt to automatically format your Swaggo annotations for better consistency and readability.

Introduction to Swagger and Swaggo

In this video, we will talk about how we can add Swagger support to our Go lang API. For those who don't know what Swagger is, it actually allows you to visualize and interact with your API's resources. This is a Swagger demo. I will put the link in the description so you can actually explore what kind of features Swagger has. You know, you can see the post, get, and delete endpoints and you can actually interact with them.

But, this video is not about what Swagger is. In this video, we will just talk about how we can integrate our Go lang API with Swagger. And we will integrate our Swagger with Swaggo library. This library actually allows you to generate Swagger documentation with Go annotations. How? Let's see together. This library actually can work with a lot of web frameworks, which we will work with Fiber. So, this library works like this.

Overview of Swaggo Annotations

For example, this is an endpoint, that get endpoint, and with annotations, we can just write like what these endpoints do in detail or in summary, how it should be grouped in Swagger, what is the parameters, like is this parameter mandatory or not, what is the type of it, which could be path, header, or body, or things like that, which is in the documentation if you want to explore further, which response status codes and types and objects, what kind of return options we have in the endpoint, and what is our route, like this.

So, this is how in general we can create our documentation for specific endpoints.

Reviewing the Refactored Go API

So, let's integrate our API to Swagger. Before start that, in the last video, we actually created our API with Fiber. If you don't know what Fiber is or how you can create endpoints and middlewares, you can check out the last video from here or here. And we have written actually all the code in the main Go section. So, right now this is a little bit verbose. So, I have actually folded them, and this is our last version. It is the same code, just with folding.

In our controller folder, we have two endpoints like get order by code and create order. Our endpoints, I just moved them to the controller folder, and this is our model. This is our correlation ID middleware, and it was just for specific endpoint. Now, it works for all of the endpoints that starts with orders. And this is our validation code. We were just selling to young people, is if you remember. We just want to sell people that older than 18 because we don't want to get into trouble with the country. And this is our main code. It is the same code, you know, just move this code to their folders. And that's it.

Installing Dependencies and Initializing Swaggo

Now, we can start to download our library and integrate it with Swagger. For Fiber, let's go let's get into the Fiber web framework section and download our library like this. Or just this. I want to do that because it is newer. Go install.

Okay, it installed. And right now, we can use the swag init command so it can generate the docs folder and swagger.json swagger.yaml file. When we do a change, we will actually use this command. So, swag init. And okay, now it has created the docs folder and it has docs.go, it has swagger.json and swagger.yaml. Great.

Now, we can download our Fiber Swagger library. Download. Great.

Now, we can import our Swagger library and start documentation. So, in our import.yaml, we need to import our Swagger Fiber and our docs folder. So, this is our Swagger. And we need to import our docs folder. So, yt swagger docs. Typo. It should be like this. And okay. Now that we have imported our library, we can register it to our app. So, we need to get app get, which works for Swagger. Swagger. And our handler is a default handler, so we will just use the swagger.default handler. And that's it.

Adding Main API Info and First Test

Now, we can start to write our annotations. So, before we start to endpoints, we can document the main API section, like write something to here, like we have order API, so we can use order API. We can write order API to here, something like that. So, we need to add it to our main function. I will just copy it from here.

Okay, I've copied it. And in here, we can just say this is an order API. We have orders. Blah blah blah. And this is an order API just for young people. Yes, that's great.

Now, run our project. This is our port. Now, in here, I'm just refreshing and I'm getting to our Swagger endpoint, and yes, we have our Swagger, but we can't see our order API because we should always run our swag init command. So, I will just run swag init. And swag format, which formats our annotations. This is right now good, but if it would have but it lacks for indentation and things like that. So, swag format. Load. And yes, like as you can see, it added space to here. Now, we can start again, running and refreshing, and as you can see, we have order API, and this is an order API for just for young people.

Now, we can start to write documentation for our endpoints.

Documenting the GET Order Endpoint

So, let's get to our endpoint, like our orders endpoint, and start to write. What does our endpoint? What is our endpoint's name? So, as you can see in here, let's just get this so I can explain to you easily. This is name of our function, like get order. This is getting orders by code. This is just name.

This is our summary as well and description as well. Maybe this is in detail. So, we can see the description. I just write written that. Our tag is like how we how we should group our orders, like orders. So, if it would have another controller in here, and they should have probably they would have different tags. You can think about it like this is per controller.

We are getting JSON, accepting, and returning our JSON. So, our param is order code, right? And we are getting our order code from the path. It is string, and it is mandatory. We need to turn this to true. And this is our description section, and our description is code of order. We don't need this format.

And we have correlation ID in here, as you can see, so we need to add a second parameter here, and that is X-Correlation-ID, and we are getting it from the header. If you want to see the what kind of types we have in param, as you can see it from param types. As you can see, we have query param, header, body, and form data. So, this is our header. If it successful, we are just returning a string in here. We don't have failure for this kind for this endpoint, but we will have in here. So, I'm just deleting here for our router. This is write orders code, and we have order code. And this is a get endpoint, so I'm leaving it as it is. Okay.

Now, I can run the swag init command. And let's format it as well. Yes. And run our function. Okay, let's come here and refresh it, and right now, we can see our endpoint. So, it is orders code order code, getting order by code. This is the summary section, and this is the description section in our annotation. We have our header, path, and we are returning 200. That's great.

Now, let's try it. So, we have order code, blah blah blah. We need to have a guid in here. Let's try this if it is working. Yes. So, I will just generate some guid here and put it to here. And this is your order code, 40 blah blah blah. That's great. Now, we have created our first endpoint with Swagger. And this is the tag section, orders. In the second endpoint, if you if you would have another tag, it would be in another section. But, this is the same order. But, that endpoint is about order as well, so we need to have the same tag.

Documenting the POST Create Order Endpoint

So, let's write our second endpoint, and that is about creating order.

Create order. Name is creating order. Our summary is creating order with request with given request in description. Our tag is the same, and we have correlation ID in here as well. It is mandatory because we have it in our correlation ID middleware. We are controlling it. As you can see, if it starts with orders, it controls. If we have some validation error in our request, we are returning bad request. So, we need to have a failure section in here. A failure section. Failure. So, which is 400. We are returning a string, and we can write a description here as well, like bad request. So, we can see as an additional section in Swagger. I will show it.

And our URL is just orders, and this is a post endpoint. We don't have actually order code. We have a request in here, right? And we are getting it from the body. And our type is not string, it's actually a custom type, and that is model.CreateOrderRequest. You can just write it like here, like this, and it is mandatory. And it is request of creating order object, something like that.

Now, let's run our Swagger command, so it generates it to our Swagger JSON and Swagger YAML. So, I will just get here and format it as well. Okay, great. Let's open here. As you can see, we have Swagger JSON and Swagger YAML file here. And when I re-fresh it, if you are using JetBrains products, you can actually use here as well. This is an additional section. You can try it from here as well. It's just about habits, actually. So, let's see the documentation in our browser. I'm refreshing it. And we can't see anything else. Why? Because we didn't run it again. So, I'm running it again. And we have our orders post endpoint.

It is about creating order. This is our description. We have two kind of responses possible responses, and we have our request object, as you can see. And there is a model section in here. As you can see, this is actually giving details about our request object. And we can add descriptions to here as well, and we will do it in a minute. And let's try if it is working or not. So, we have We need to have a guid. This is our guid. 10 TR for Turkey. MF care order code. I don't know, something like that. It says age is failed because we are under 18. So, let's put it as 20. And order created successfully, 201. Great. Our endpoint works. And we have two endpoints under the same tag, orders.

Documenting Model Structs and Final Recap

So, as I said before, we can add descriptions to here if we have complex objects. And if you do think we need to actually put descriptions to our request as well, we can add annotations to them as well. So, let's do it to our request object. This is our request object. Okay, let's What is the name of it? This is create order request. And we can add a description to here like this.

Description, request about creating order. We can just add comment line to here and add description like shipment no of order. And this is country like TR, EN like TR, US, etc. And for here, we can say age, make sure you are young. Okay.

Let's run our Swagger command. Let's format it as well. This is an additional thing. Let's run it. Okay, and refresh. And in here, as you can see, we have our description. And we have our detailed description for every property as well. And this is how you can enrich your Swagger endpoint, your Swagger documentation.

And that's how you can integrate your going API with Swagger. Swagger also supports a lot of web frameworks, not just for Fiber. You can explore the project in detail. I'll put the link in the description. That's it for today. Thanks for watching. May the force be with you.