First steps

This tutorial assumes, that you already have Golang installation and basic knowledge about how to build and run Go programs. If this is your first hit with Go, and you feel you have no idea what is happening here, please read how to get started with Go.

Ok, so let's create a project:

$ mkdir gnext-example
$ cd gnext-example
$ go mod init example.com/gnext
$ go get -u github.com/meteran/gnext
---> 100%

Create a file example.go and fill it up with the following code:

package main

import "github.com/meteran/gnext"

func main() {
    r := gnext.Router()

    r.GET("/example", func() string {
        return "Hello World!"
    })

    _ = r.Run()
}

Run it:

$ go run example

Now you can visit this link in your browser: http://localhost:8080/example

Yes, yes... of course it works, but that's boring... Let's open this page: http://localhost:8080/docs

Whoa, that was amazing, ...but not very useful.

Let's try some real example. With request and response. We can modify our handler to use structures:

package main

import "github.com/meteran/gnext"

func main() {
    r := gnext.Router()

    r.POST("/example", handler)
    _ = r.Run()
}

type MyRequest struct {
    Id   int    `json:"id" binding:"required"`
    Name string `json:"name"`
}

type MyResponse struct {
    Result string `json:"result"`
}

func handler(req *MyRequest) *MyResponse {
    return &MyResponse{Result: req.Name}
}

Restart the server and visit the docs page. You can see that request and response of POST /example endpoint are documented. That's the real power!

The POST request without required id now fails with the validation error:

$ curl --request POST http://localhost:8080/example --data '{"name": "some name"}'

gives output:

{
  "message": "validation error",
  "details": [
    "field validation for 'id' failed on the 'required' tag with value ''"
  ],
  "success": false
}

the valid request:

$ curl --request POST http://localhost:8080/example --data '{"name": "some name", "id": 4}'

gives us the expected response:

{
  "result": "some name"
}

Congratulations! Now you are prepared for the fast forwarding development of your great API.