gin-scalar

A gin middleware that helps automatically generate RESTful API documentation with Scalar.

Note

Unlike Swagger implementations, this middleware bundles Scalar, and it does not need a separate files package.

Usage

Start using it

1. Add comments to your API source code, See Declarative Comments Format.
2. Download Swag for Go with:

go install github.com/swaggo/swag/cmd/swag@latest

3. Run Swag at your Go project root path, Swag will parse comments and generate the required files (docs folder and docs/doc.go).

swag init

4. Download gin-scalar with:

go get -u github.com/tinyauthapp/gin-scalar

Import the middleware:

import "github.com/tinyauthapp/gin-scalar"

Canonical example

Now assume you have implemented a simple API as follows:

// A get function that returns a hello world string by JSON
type HelloWorldResponse struct {
    Message string `json:"message"`
}

func HelloWorld(ctx *gin.Context)  {
   ctx.JSON(http.StatusOK, HelloWorldResponse{
   Message: "Hello, World!",
   })
}

Now, add the scalar middleware to your gin router:

1. Add comments in the API and in the main function:

type HelloWorldResponse struct {
	Message string `json:"message"`
}
// @BasePath /api/v1

// HelloWorldExample godoc
// @Summary Hello World Example
// @Description Just return a hello world string
// @Tags example
// @Produce json
// @Success 200 {object} HelloWordResponse
// @Router /example/helloworld [get]
func HelloWorld(ctx *gin.Context)  {
    ctx.JSON(http.StatusOK, HelloWorldResponse{
		Message: "Hello, World!",
    })
}

2. Use the swag init command to generate the docs, the generated docs will be stored at docs/.

3. Add the scalar middleware to your gin router:

package main

import (
   "github.com/gin-gonic/gin"
   docs "github.com/go-project-name/docs"
   ginScalar "github.com/tinyauthapp/gin-scalar"
   "net/http"
)
type HelloWorldResponse struct {
   Message string `json:"message"`
}
// @BasePath /api/v1

// HelloWorldExample godoc
// @Summary Hello World Example
// @Description Just return a hello world string
// @Tags example
// @Produce json
// @Success 200 {object} HelloWorldResponse
// @Router /example/helloworld [get]
func HelloWorld(ctx *gin.Context)  {
   ctx.JSON(http.StatusOK, HelloWorldResponse{
      Message: "Hello, World!",
   })
}

func main()  {
   r := gin.Default()
   docs.SwaggerInfo.BasePath = "/api/v1"
   v1 := r.Group("/api/v1")
   {
      eg := v1.Group("/example")
      {
         eg.GET("/helloworld", HelloWorld)
      }
   }
   r.GET("/scalar/*any", ginScalar.WrapHandler(nil))
   r.Run(":8080")
}

Demo project tree, swag init is run at the root path of the project.

.
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
└── main.go

Configuration

You can configure Scalar using different configuration options. For example:

ginScalar.WrapHandler(nil, ginScalar.URL("http://localhost:8080/swagger/doc.json"))

Option	Type	Default	Description
URL	string	"doc.json"	URL pointing to API definition (normally swagger.json or swagger.yaml)
InstanceName	string	"swagger"	The instance name of the swagger document. If multiple different swagger instances should be deployed on one gin router, ensure that each instance has a unique name (use the --instanceName parameter to generate swagger documents with swag init).
BasePath	string	"/scalar"	The base path in which the Scalar UI will be served
ProjectName	string	"Scalar"	Project name displayed as the page title of the Scalar UI

License

Licensed under MIT.