Create a REST API Using Swagger in Go Part 1

Have you ever wondered if REST APIs can be built using Go? Aside from DevOps and CLI tools, Web Development is a place where Go can shine in large scale projects. According to the most recent developer survey on the official Go website, 65% of go developers work on web development. With that in mind, I figured it would be a cool idea to write about how I use Go in my day-to-day as a backend engineer.

Before we get started, it is assumed the reader has at least some familiarity with basic HTTP and REST concepts. It is also assumed Go is installed, if not you can follow these directions to do so. In this post, we’ll be going over the basics of what swagger is and how it works, then we’ll create some endpoints in the next part.

What is Swagger?

Go has a built-in network package that works really well and you may see other posts starting there when doing an intro to REST APIs, but I’d like to jump right into using something a little more production-ready called Swagger (formerly Open-API). Swagger is a library that supports the Go language and makes building APIs a lot easier by removing the need to write boilerplate code and offering a really cool solution for documentation. Although this comes with a lot of functionality and flexibility out of the box, we will be going over just the basics. You can check out more here on the official website after the tutorial if you want to get more in-depth.

Getting Started

The first thing we want to do is create a Go project and name it whatever we want, I chose “swag-api” for simplicity. After that we’ll create a standard main.go file inside that directory with the usual starter code for now.

package main

func main() {
}

Next, because we’re working with modules in this project, it makes sense to turn our project into a module to better coordinate with the swagger package. To do this, we’ll need to run a `go mod` command and specify a URL location. We won’t be doing anything with the URL so don’t worry if it sounds a bit confusing. Turning our package into a module also frees us from having to create Go projects inside the go directory. It’s best practice to use a GitHub URL for the go mod command so let’s do that. Open up a terminal within your project directory and run this command:

go mod init github.com/<Your Github profile name here>

You’ll know it was successful if you see a go.mod in your directory. Nice! Next, we’ll follow that up by downloading the go-swagger module:

go install github.com/go-swagger/go-swagger/cmd/swagger

If this was successful, you should be able to click into your go.mod file and see something like this as the bottom:

require github.com/go-swagger/go-swagger v0.23.0 // indirect

If anything changes it should be the version number at the end. But aside from that congratulations, you have officially installed swagger for your project!

How Swagger Works

Using Swagger to build and document an API in Go might work a little differently than it would in other languages or frameworks. The main component consists of a YAML file (.yml) that serves as a configuration file. This file is used to generate the boilerplate API code and documentation so that you as a developer can focus on the more important parts of the code. Start by generating a bare-bones config file in our project by running this in the command line:

swagger init spec \
  --title "A Trivia application" \
  --description "From the swagger tutorial on justanother.dev" \
  --version 1.0.0 \
  --scheme http \
  --consumes application/json \
  --produces application/json

If it works, you should see a swagger.yml file Before we move any further, let’s go through this command line by line. Starting with the command itself, we then see a \ which indicates starting a new line without finishing the command. Next there is a line for the title and description of the API we are building. After that is a version, which we are specifying ourselves as version 1.0.0. Then there is a line designating the scheme we want to use which is HTTP (this also includes HTTPS). The final two lines specify what format we are accepting (consuming) and serving (producing) from our REST API, JSON.

Editing Config File

While it is certainly possible to edit the YAML file by hand, there are a few resources to make it a lot easier. The two common platforms are the swagger online editor and Stoplight, which has an online editor and an offline editor. For now, let’s use the Stoplight online editor by hitting the start button on the home page. Give the local project a name (I reused swag-api here) press create, don’t worry about the checkbox asking to include tutorial files. You should see a screen that looks something like this:

Click on the API button and give it a name, “api” should be good enough, then press Create. We just creat In the top right you should see a button labeled Code, press that and paste the contents from the swagger file that we generated here.

Nice! Now let’s create our first endpoint. Right-click the Paths section on the left and select New Path. This is where we declare our endpoint addresses in the swagger project. No need to worry about the base URL of the endpoint, only what comes after, so let’s call it “/question”. 

Imagine we’re going to use this as the endpoint for adding questions to a database, it’ll need to be a POST method that takes a few fields. Newly created paths come with GET methods automatically, which we don’t want right now, so right-click the path and select “delete GET operation.” You can create the POST method by selecting the form button in the top right, and clicking on + POST operation. You should an empty form like this:

Go ahead and fill out the following fields like so:

 

Now we need to take this back to our project; click on the code button again and you should see the new endpoint in the YAML code. Copy this, paste it into the YAML file in your project. In order to generate the API code for our endpoint we need to tell swagger to analyze the file, but first, create a fold in the project called gen. This is where the output of the generated code will go. Our directory should look like this right now:

/swag-api
   /gen
   main.go
   go.mod
   swagger.yml

Run this command in the terminal in your project directory:

swagger generate server -t gen -f ./swagger.yml --exclude-main

This tells swagger to create server code in a location titled gen, the location of the config file, and not to include the out of the box main.go file that would otherwise be generated as well. If done correctly, you should see a number of files pop up within the gen folder, created by swagger. 

Conclusion/Part 2

Just to make sure this post doesn’t run on and on, I think it’ll be good to finish here for now. In part 2, We’ll go do a quick overview of some of the code we generated, hook up our first API endpoint in the code, and go over some other things we can add to our yaml file. If you’ve made it this far, you should definitely be proud of yourself! See ya soon. 

Leave a Comment

Your email address will not be published. Required fields are marked *