Building an API Using Beego + Swagger

Published in

MDG Space

4 min readNov 21, 2019

Why Beego?

Beego, a RESTful HTTP framework, is built for the development of web applications and APIs in Golang and follows the Model-View-Controller(MVC) architecture. It supports Swagger for automated documentation generation, which makes our work easier.

In this post, I will be discussing the basics of the Beego framework and how Swagger can help us in the documentation.

Prerequisites

Go setup (follow this)
Beego installation (follow this)

Let’s get started

Assuming you have successfully set up Go and Beego, it’s time to get started!
First, I want you to run a simple command in the terminal.

bee

This should output something like:

If your output matches with this, it confirms that you have successfully set up everything needed for this project. If not, go ahead and troubleshoot the problem.

Let’s make a new API for this tutorial, naming it test_api

bee api test_api

This command will create a directory “test_api” with the following folders and files:

-conf
-controllers
-main.go
-models
-routers
-tests

In very brief, routers is the place to specify your endpoints, controllers are the brain of your API, models are for the data handling required by the controllers and conf is the configuration file to store credentials and other information about API.

We will already be having the “user” and “object” endpoints created by default in the router.go file in the routers directory.

This code snippet specifies that the endpoint v1/object is handled by the ObjectController . I have created a test endpoint following similar norms for this tutorial. For now, we can ignore all the other keywords here and focus only on the endpoint and the controller handling the endpoint.
Whenever a call is executed to the v1/test endpoint, the logic inside the TestController would be executed.

We would now need to make two new files: test.go in controllers and test.go in models.
test.go in controllers is basically the TestController and the model's file is the model for this specific controller.

The layout for every controller is the same, so we can actually use the user controller’s code here and modify it according to our need. Coming to the function Test() , whenever this function is executed, the Response variable calls the function TestFunction in models and stores the data received. The controller then encodes the data into the JSON form and returns it.

That’s simple.
But what is more important here is to understand the comments preceding the TestFunction .
These comments actually play a role in the API and the documentation.
The comments @Title and @Description are self-descriptive of their functionalities and are of use for documentation.
@Success and @Failure indicate the responses on success and failure of execution of the endpoint respectively. The integer succeeding these comments indicate the response code, and the values succeeding these integers indicate the return type. These comments are also for documentation.
The last comment, @Router implies what the endpoint would be and it’s functionality. /hello after @Router is in addition to the initial endpoint specified in router.go, i.e. the function Test would be executed when the endpoint v1/test/hello would be called for. [get] means that the HTTP request is a GET request.
Learn more about HTTP requests here.
A detailed explanation about such comments in the Beego framework could be obtained here.

Coming to the model’s code :

The function TestFunction , having return type as struct Test , is called by the controller. It creates a new variable for the struct, assigns Response as “Hello World” and returns the struct.
All the data handling and modification should be executed here.

Congratulations! We have completed coding our API for this tutorial. Now is the time to test our API and generate some docs.

bee run

Use this command in the directory test_api to run our local server to test our endpoints. Now, open the browser and type :

http://localhost:8080/v1/test/hello

The output should be :

{
  "Response": "Hello World"
}

Now coming to the auto-generation of documentation, end the server’s session and use this command :

bee run -gendoc=true -downdoc=true

Now, go to the browser and type :

http://localhost:8080/swagger/

This is the auto-generated documentation of our API. We can see the documentation of our endpoint.

Voila! This is the end of this tutorial. I hope you learned something valuable from it. I am posting some important links below for you to get better at Beego development.

Building an API Using Beego + Swagger

Why Beego?

Prerequisites

Let’s get started

Links

Written by Arnesh Agrawal