Getting Started

Let's run Gleece.

Configure Service

Gleece integrates into an existing server with a router.

info

Gleece supports Gin, Echo v4, Gorilla Mux, Chi v5, and Fiber v2 routers.

See routers for more info on integrating other routers.

This introduction will be demonstrated with the popular Gin router, but all the rest are very similar.

A simple server might look like this:

main.go

package main

import (
    "net/http"

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

func main() {
    // Create a default Gin router
    router := gin.Default()

    // Define a route for GET /hello
    router.GET("/hello", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "Hello World!",
        })
    })

    // Start the server on port 8080
    router.Run("127.0.0.1:8080")
}

Importing Gleece

Add Gleece's runtime package to the app's codebase:

go get github.com/gopher-fleece/runtime

And install the Gleece CLI:

go get github.com/gopher-fleece/gleece
go install github.com/gopher-fleece/gleece

info

The github.com/gopher-fleece/gleece package is only used during build time to generate the routers and the specification, and not needed to be added to server's go.mod. Run go mod tidy to clean up your dependencies graph.

Gleece Configuration

Create a basic Gleece configuration file named gleece.config.json:

gleece.config.json

{
	"commonConfig": {
		"controllerGlobs": [
			"./*.go",
			"./**/*.go"
		]
	},
	"routesConfig": {
		"engine": "gin",
		"outputPath": "./dist/gleece.go",
		"outputFilePerms": "0644",
		"authorizationConfig": {
			"authFileFullPackageName": "",
			"enforceSecurityOnAllRoutes": true
		}
	},
	"openapiGeneratorConfig": {
		"openapi" : "3.0.0",
		"info": {
			"title": "Sample API",
			"description": "This is a sample API",
			"termsOfService": "http://example.com/terms/",
			"version": "1.0.0"
		},
		"baseUrl": "https://api.example.com",
		"securitySchemes": [
			{
				"description": "API Key for accessing the API",
				"name": "securitySchemaName",
				"fieldName": "x-header-name",
				"type": "apiKey",
				"in": "header"
			}
		],
		"defaultSecurity": {
			"name": "securitySchemaName",
			"scopes": [
				"read",
				"write"
			]
		},
		"specGeneratorConfig": {
			"outputPath": "./dist/swagger.json"
		}
	}
}

See the full configuration documentation for detailed explanation of all available properties.

Define Authentication

Create a module and Go file for the authentication function, assuming it is auth/security.go. Set the package path where your security check function is located in the routesConfig->authorizationConfig->authFileFullPackageName.

Inside the file, paste the following code. Modify the logic in GleeceRequestAuthorization to fit your needs:

auth/security.go

package auth

import (
	"github.com/gin-gonic/gin"
	"github.com/gopher-fleece/runtime"
)

func GleeceRequestAuthorization(ctx *gin.Context, check runtime.SecurityCheck) *runtime.SecurityError {

	authHeader := ctx.GetHeader("Authorization")
	if authHeader == "change that condition...." {
		return &runtime.SecurityError{
			StatusCode: 403,
			Message:    "You are not authorized to read that API",
		}
	}
	return nil
}

Creating Controllers

Create the controller controllers/user.ctrl.go.

First, create a struct and embed the GleeceController in it. Then add a route method to the struct with the Gleece annotations:

controllers/user.ctrl.go

package controllers

import (
	"github.com/gopher-fleece/runtime"
)

// UsersController
// @Tag(Users) Users
// @Route(/users)
// @Description The Users API
type UsersController struct {
	runtime.GleeceController // Embedding the GleeceController to inherit its methods
}

// @Description Get user data
// @Method(GET)
// @Route(/{id})
// @Path(id) The id of the user to get
// @Response(200) The user's information
// @ErrorResponse(404) The user not found
// @ErrorResponse(500) The error when process failed
// @Security(securitySchemaName, { scopes: ["read:users" ] }) Consumer should pass this security schema
func (ec *UsersController) GetUser(id string) (string, error) {
	return "", nil
}

Every route function must declare at least one return type: error. For operations without a response payload, error will be the only return type. For operations that return data, the response payload (string, struct etc.) must be the first return value, followed by error as the second return value.

tip

To enhance your development experience with Gleece, we provide an official VSCode extension that provides intelligent annotation highlighting and improved code visibility.

Running the Gleece Generator

Now it's ready to run the Gleece generator.

Run the Gleece generator in your terminal:

gleece

By default, it reads the gleece.config.json configuration file. It generates routes based on the engine specified in routesConfig->engine. It also generates the OpenAPI specification according to the version set in openapiGeneratorConfig->openapi.

In this example configuration, it generates gin routes and OpenAPI v3.0.0 specifications, with both outputs in the dist directory.

Integrating Generated Routes

Import the newly created routes into your main.go module and register the Gin instance to the generated code:

main.go

package main

import (
    "net/http"

    gleeceRoutes "<package>/routes"

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

func main() {
    // Create a default Gin router
    router := gin.Default()

    // Define a route for GET /hello
    router.GET("/hello", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "Hello World!",
        })
    })

    // Register the routes from the generated code
    gleeceRoutes.RegisterRoutes(router)

    // Start the server on port 8080
    router.Run("127.0.0.1:8080")
}

And... start the application.

tip

For a complete example project using Gleece, check out the Gleece Example Project.

This project demonstrates how to set up and use Gleece in a real-world scenario, providing you with a practical reference to get started quickly.