gorilla/mux framework (rk-boot): add Swagger UI

introduce

This article will describe how to provide Swagger UI on top of gorilla/mux framework.

Please visit the following address for the complete gorilla/mux tutorial:

• https://github.com/rookie-ninja/rk-mux

prerequisites

gorilla/mux does not have its own function to generate Swagger UI configuration files.

We need to install the swag command line tool to generate the Swagger UI configuration file.

Installation options: via swag official website

$ go get -u github.com/swaggo/swag/cmd/swag

install rk-boot

We introduce the rk-boot library, users can quickly build gorilla/mux microservices .

• Documentation
• source code

go get github.com/rookie-ninja/rk-boot/mux

quick start

1. Create boot.yaml

The boot.yaml file will tell rk-boot how to start the gorilla/mux service. In the following example, we specify the port, the json file path of the Swagger UI.

---
mux:
  - name: greeter        # Required
    port: 8080           # Required
    enabled: true        # Required
    sw:
      enabled: true      # Optional, default: false
      jsonPath: "docs"   # Optional, default: ""
#      path: "sw"        # Default value is "sw", change it as needed
#      headers: []       # Headers that will be set while accessing swagger UI main page.

2. Create main.go

In order for the swag command line to generate the Swagger UI parameter file, we need to write comments in the code.

For details, please refer to the official swag documentation.

// Copyright (c) 2021 rookie-ninja
//
// Use of this source code is governed by an Apache-style
// license that can be found in the LICENSE file.

package main

import (
	"context"
	"fmt"
	"github.com/rookie-ninja/rk-boot"
	"github.com/rookie-ninja/rk-boot/mux"
	"github.com/rookie-ninja/rk-mux/interceptor"
	"net/http"
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample rk-demo server.
// @termsOfService http://swagger.io/terms/

// @securityDefinitions.basic BasicAuth

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email [email protected]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
func main() {
	// Create a new boot instance.
	boot := rkboot.NewBoot()

	// Register handler
	entry := rkbootmux.GetMuxEntry("greeter")
	entry.Router.NewRoute().Methods(http.MethodGet).Path("/v1/greeter").HandlerFunc(Greeter)

	// Bootstrap
	boot.Bootstrap(context.TODO())

	boot.WaitForShutdownSig(context.TODO())
}

// @Summary Greeter service
// @Id 1
// @version 1.0
// @produce application/json
// @Param name query string true "Input name"
// @Success 200 {object} GreeterResponse
// @Router /v1/greeter [get]
func Greeter(writer http.ResponseWriter, request *http.Request) {
	rkmuxinter.WriteJson(writer, http.StatusOK, &GreeterResponse{
		Message: fmt.Sprintf("Hello %s!", request.URL.Query().Get("name")),
	})
}

// Response.
type GreeterResponse struct {
	Message string
}

3. Generate swagger parameter file

By default, three files are created in the docs folder. rk-boot will use swagger.json to initialize the Swagger UI interface.

$ swag init

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

1 directory, 7 files

4. Verify

Visit: localhost:8080/sw

{{o.name}}

{{m.name}}