Gorilla/mux framework (RK boot): add swagger UI

Introduce

This article will show you how to gorilla/mux Provided above the framework Swagger UI.

Please visit the following address for complete information gorilla/mux course ：

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

precondition

gorilla/mux No built-in generation Swagger UI The function of configuration file .

We need to install swag Command line tools to generate Swagger UI The configuration file .

Installation options ： adopt swag Official website

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

install rk-boot

Let's introduce rk-boot library , Users can quickly build gorilla/mux Microservices .

• file
• Source code

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

Quick start

1. establish boot.yaml

boot.yaml The file will tell rk-boot How to start gorilla/mux service , In the following example , We specified the port ,Swagger UI Of json File path .

---
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. establish main.go

In order to make swag Command line generation Swagger UI Parameter file , We need to write comments in the code .

Please refer to swag Official documents .

// 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

The default will be docs Create three files in the 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. verification

visit ：localhost:8080/sw