Tutorials on I'm Gilmar Soares

How to Publish Your Go Library on Pkg Go

Thu, 31 Oct 2024 14:38:09 -0300

Continue my way to learn Go in a deep way, today I’ll show to you how to publish you library in Pkg.Go

First of all, you need to have a Go library in you Github account or any other Git repository. In this example, I’ll use a simple library that I created to show how to publish it.

The library is valid-brazilian-cnpj. In Brazil we have a document called CNPJ, the next year the rules to validate it will change, so I created this library to help me to validate CNPJ.

How I create this library is not the focus of this post, but if you want to see the code, you can access the repository.

To publish your library in Pkg.Go, you need to create a release in your repository.

First Step - run go mod tidy

The first step is to run go mod tidy to make sure that all dependencies are in the go.mod file.

go mod tidy

Second Step - Run tests

The second step is to run the tests to make sure that everything is working as expected.

go test -v

This command will run all tests in the library and show the results.

Third Step - Create a tag

The third step is to create a tag in your repository.

git tag v0.1.0
git push origin v0.1.0

This command will create a tag called v0.1.0 and push it to the repository.

Fourth Step - Push this to Pkg.Go

GOPROXY=proxy.golang.org go list -m github.com/linuxsoares/valid-brazilian-cnpj@v0.1.1

Explaining the command:

GOPROXY=proxy.golang.org: This is the URL of the Pkg.Go
go list -m github.com/linuxsoares/valid-brazilian-cnpj@v0.1.1: This command will push the library to Pkg.Go

After running this command, you can access the library in Pkg.Go.

Conclusion

In this post, I showed you how to publish your library in Pkg.Go. This is a simple process, but it’s important to follow the steps to make sure that everything is working as expected.

I hope you enjoyed this post and see you in the next one.

Happy coding!

How to Document Your Go API

Thu, 24 Oct 2024 16:22:02 -0300

Today, I’m writing a technical post about API documentation in Go. I hope you find it useful!

First, we’ll create a simple CRUD API using Go and the Gin framework. Let’s get started!

package main

import (
	"net/http"
	"strconv"

	"github.com/gin-gonic/gin"
)

type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

var users = []User{
	{ID: 1, Name: "John"},
	{ID: 2, Name: "Doe"},
}

func main() {
	r := gin.Default()

	// Change to default is /api/v1
	api := r.RouterGroup.Group("/api/v1")
	{
		api.GET("/users", getUsers)

		api.GET("/users/:id", getUser)

		api.POST("/users", createUser)

		api.PUT("/users", editUser)

		api.DELETE("/users/:id", removeUser)
	}

	r.Run(":8080")
}

func getUsers(c *gin.Context) {
	c.JSON(http.StatusOK, users)
}

func getUser(c *gin.Context) {
	id, _ := strconv.Atoi(c.Param("id"))
	userFound, _ := findUserByID(users, id)
	c.JSON(http.StatusOK, userFound)
}

func createUser(c *gin.Context) {
	var user User
	c.BindJSON(&user)
	users = append(users, user)
	c.JSON(http.StatusCreated, user)
}

func editUser(c *gin.Context) {
	var user User
	c.BindJSON(&user)
	putUser(users, user)
	c.JSON(http.StatusOK, user)
}

func removeUser(c *gin.Context) {
	id, _ := strconv.Atoi(c.Param("id"))
	deleteUserByID(users, id)
	c.JSON(http.StatusOK, nil)
}

func findUserByID(users []User, id int) (*User, bool) {
	for _, user := range users {
		if user.ID == id {
			return &user, true
		}
	}
	return nil, false
}

func deleteUserByID(users []User, id int) []User {
	newUsers := []User{}
	for _, user := range users {
		if user.ID != id {
			newUsers = append(newUsers, user)
		}
	}
	return newUsers
}

func putUser(users []User, newUser User) []User {
	for i := range users {
		if users[i].ID == newUser.ID {
			// Update the existing user
			users[i] = newUser
			return users
		}
	}
	// Add new user if not found
	return append(users, newUser)
}

Now that we have a simple CRUD API in Go, let’s document it.

Note: In this example, I didn’t use the best approach for a CRUD. Instead, I defined a User struct to represent a user and used a slice to store the users. In a real-world project, you should use a database to store the data. Additionally, while I used basic functions to manipulate the data, it’s recommended to follow the repository pattern in production code.

With that out of the way, let’s move on to creating our documentation.

First, we’ll create a Makefile to simplify managing the app.

run:
    go run main.go

build-swagger:
	@go run github.com/swaggo/swag/cmd/swag@latest init -g main.go -o docs

Now, we need to install some dependencies to use Swag.

    go get -u github.com/swaggo/gin-swagger
    go get -u github.com/swaggo/files

Now, I need to add some descriptions using code comments in the main function.

// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
func main...

We need to add a route to serve the Swagger documentation.

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

Now, we need to run a command to generate the documentation.

make build-swagger

With all the Swag configurations complete, we can run the app and access the documentation in the browser.

make run

Now, access the URL http://localhost:8080/swagger/index.html to view the documentation.

Below is an example of how to document a CRUD:

GET USERS:

// @BasePath /
// ShowAccount 	 godoc
// @Summary      Show a Users list
// @Description  get users
// @Tags         getUsers
// @Accept       json
// @Produce      json
// @Router       /users  [get]

GET USER:

// @BasePath /
// ShowAccount 	 godoc
// @Summary      Show a Users list
// @Description  get users
// @Tags         getUsers
// @Accept       json
// @Produce      json
// @Param        id         path      string  true  "ID"
// @Router       /users/{id}  [get]

POST:

// @BasePath /
// ShowAccount 	 godoc
// @Summary      Create a User
// @Description  create users
// @Tags         createUser
// @Accept       json
// @Produce      json
// @Param user body User true "User to create"
// @Router 		/users [post]

PUT:

// @BasePath /
// ShowAccount 	 godoc
// @Summary      Edit a User
// @Description  edit users
// @Tags         editUser
// @Accept       json
// @Produce      json
// @Param user body User true "User to edit"
// @Router 		/users [put]

DELETE:

// @BasePath /
// ShowAccount 	 godoc
// @Summary      Remove a Users list
// @Description  delete user
// @Tags         removeUser
// @Accept       json
// @Produce      json
// @Param        id         path      string  true  "ID"
// @Router       /users/{id}  [delete]

With these comments in each function, we can generate the documentation using Swag.

The result is:

You can view the project in the repository.

Conclusion

In this article, we learned how to document a Go API using Swag. We started by creating a simple CRUD API in Go and then documented it using Swag. We also learned how to generate the documentation and view it in the browser.

Swag is a powerful tool that can help you document your Go APIs easily.

I hope you found this article helpful. If you have any questions or suggestions, feel free to send me a message in my social media accounts.

Thank you for reading!

Duck Typing in Go

Thu, 10 Oct 2024 13:46:16 -0300

Hello everyone!

As I mentioned in a previous post, I’m currently learning Go to use in some of my work projects. In this short post, I’ll explain how to use duck typing in Go, which was quite challenging for me when I first started learning the language.

To begin, let’s look at a simple example in Python:

class Duck:
    def quack(self):
        print("Quack, quack!")


class Person(Duck):
    pass


def quack(obj):
    obj.quack()

def main():
    donald = Duck()
    john = Person()

    quack(donald) -- Quack, quack!
    quack(john) -- Quack, quack!

In this somewhat quirky example, the Person class can “quack” like a Duck because it inherits from the Duck class. In Python, we don’t need to explicitly declare the type of the object in the function; we simply call the method we want to use.

Now, let’s see how to achieve something similar in Go:

package main

import "fmt"

type Dog interface {
	Bark()
}

type Cat interface {
	Meow()
}

type Shihtzu struct {
	Name string
}

type Chartreux struct {
	Name string
}

func (s Shihtzu) Bark() {
	message := fmt.Sprintf("Type: %T - My name is %s! Bark! Bark! Bark!", s, s.Name)
	fmt.Println(message)
}

func (c Chartreux) Meow() {
	message := fmt.Sprintf("Type: %T - My name is %s! Meow! Meow! Meow! ", c, c.Name)
	fmt.Println(message)
}

func main() {
	var dog Dog
	dog = Shihtzu{Name: "Puppy"}
	dog.Bark()

	var cat Cat
	cat = Chartreux{Name: "Kitty"}
	cat.Meow()
}

The example code above is in this repository on github.

In this Go example, we have two interfaces, Dog and Cat, and two structs, Shihtzu and Chartreux. The Dog interface defines a method Bark, while the Cat interface defines a method Meow. The structs Shihtzu and Chartreux implement the Bark and Meow methods, respectively. It’s important to note that although it’s not explicitly stated in the code, these structs are implementing the interfaces.

In Go, we implement an interface by simply defining the required methods, without needing to declare that the struct is explicitly implementing the interface.

In other words, we don’t need to state that Shihtzu is a Dog—we just need to implement the Bark method for the Shihtzu struct, and Go automatically understands that Shihtzu satisfies the Dog interface.

This is quite different from languages like Python or Java, but once you get the hang of it, it’s straightforward and easy to use.

I hope this post helps you better understand Go and how duck typing works in the language!

First Clojure Project

Mon, 16 Sep 2024 18:04:37 -0300

Creating Our First Clojure Project

Let’s continue with our tutorial. Today, I will explain how we can create a Clojure project. I decided to split this article into two parts: we will explain how to create a regular project and a web project, where we will create an API for some service.

Let’s start by creating a regular project. It won’t be an API, a library, or anything like that. I just want to demonstrate how to create a project, explain its structure, and everything else.

Creating a project is very simple if you’ve installed Leiningen [I mentioned it in our first article]. If you haven’t installed it yet, do yourself a favor and install it. The project link is here: Leiningen — :)

Well, if you’ve done yourself this favor and have everything nicely installed, it’s time to create the Clojure project. Let’s go:

➜ hello-clojure git:(master) ✗ lein new hello-clojure

By running the above command, you get a directory named hello-clojure because that’s the name of the project we passed as a parameter to the new command of lein.

➜ creating-clojure-project git:(master) ✗ ls

hello-clojure

The Structure of a Clojure Project

Entering the directory, you’ll have a structure with many files and subdirectories. Don’t be alarmed or leave the article; I’ll explain each one of them in detail. Here’s the project structure:

We will explain each file and directory from top to bottom:

doc: In the doc folder, you can place the documentation for your project. The intro.md file comes by default when we create the project using lein.
    Just to clarify, the .md extension is for markdown, which is widely used by GitHub, for example.

resources: The resources directory is used to store any configuration files you might need.

src: Inside src is where we will store our Clojure code related to the project.

test: The name speaks for itself, containing all the project's test files.

CHANGELOG: This is usually where we record what changes in each version of the project, whether it's in Python, Java, Clojure, or Ruby.

LICENSE: Contains the legal information that we typically click "ACCEPT" without reading.

project.clj: While resources is used for configuration files, project.clj is where we actually configure our Clojure project.

Just so you don’t end up with a project that can’t run or show the famous “HELLO WORLD,” I’ll explain how to get it running. — :)

Open the project.clj file and add the following code after :dependencies. Don’t forget it needs to be inside the parentheses.

:main hello-clojure.core/foo

After that, we can run the project from the command line inside the project directory and see the result:

➜ hello-clojure git:(master) ✗ lein run Clojure
Clojure Hello, World!

And here we have our result without errors :)

To keep this article from being too long, I’ll divide it into parts. This part is about creating the project, and another will cover using namespaces, importing them into other namespaces, and so on.

The code will be available on GitHub, and we will update it with each article.

That’s it for today. Thanks to everyone who has read so far and for the great feedback!!!

Below are the other articles and those coming soon:

Hello World;
Creating our own functions;
Using existing Clojure functions;
Creating a Clojure project;
Seeing how we create functions and reuse them in our projects;
Creating a web project;
Using Java classes in Clojure functions;
And much more…

Cheers!