swagger

README

swagger

gin swagger library.

Example of use

package main

import (
    "net/http"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/gin-gonic/gin"
	"github.com/go-dev-frame/sponge/pkg/gin/response"

	"user/docs" // docs is generated by Swag CLI, you have to import it.
)

// @title serverNameExample api docs
// @description http server api docs
// @schemes http https
// @version v1.0.0
// @host localhost:8080
// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
// @description Type Bearer your-jwt-token to Value
func main() {
	r := gin.Default()

	docs.SwaggerInfo.BasePath = ""
	// access path /swagger/index.html
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.POST("/create_user", CreateUser)

	r.Run(":8080")
}

// Create user
// @Summary create user
// @Description submit information to create user
// @Tags user
// @Accept json
// @Produce json
// @Param data body types.CreateUserRequest true "user information"
// @Success 200 {object} types.CreateUserReply{}
// @Router /api/v1/user [post]
// @Security BearerAuth
func CreateUser(c *gin.Context) {
	form := &CreateUserRequest{}
	err := c.ShouldBindJSON(form)
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"msg": err.Error()})
		return
	}
	// create user logic...

	response.Success(c, gin.H{"id": 123})
}

type CreateUserRequest struct {
	Name  string `json:"name"`
	Password string `json:"password"`
	Age   int    `json:"age"`
	Email string `json:"email"`
}

type CreateUserReply struct {
	Code int    `json:"code"`
	Msg  string `json:"msg"`
	Data struct {
		ID uint64 `json:"id"`
	} `json:"data"`
}

Test api with swagger:

1. install swag: go install github.com/swaggo/swag/cmd/swag@latest
2. generate docs: swag init
3. run server: go run main.go
4. visit http://localhost:8080/swagger/index.html in your browser

Documentation

Overview

Package swagger is gin swagger library.

Index

• func CustomRouter(r *gin.Engine, name string, jsonContent []byte)
• func CustomRouterByFile(r *gin.Engine, jsonFile string)
• func DefaultRouter(r *gin.Engine, jsonContent []byte)
• func DefaultRouterByFile(r *gin.Engine, jsonFile string)

Functions

func CustomRouter

func CustomRouter(r *gin.Engine, name string, jsonContent []byte)

CustomRouter custom swagger routing, request url is http://<ip:port>/<name>/swagger/index.html

func CustomRouterByFile

func CustomRouterByFile(r *gin.Engine, jsonFile string)

CustomRouterByFile custom swagger router from file, request url is http://<ip:port>/<filename prefix>/swagger/index.html

func DefaultRouter

func DefaultRouter(r *gin.Engine, jsonContent []byte)

DefaultRouter default swagger router, request url is http://<ip:port>/swagger/index.html

func DefaultRouterByFile

func DefaultRouterByFile(r *gin.Engine, jsonFile string)

DefaultRouterByFile default swagger router from file, request url is http://<ip:port>/swagger/index.html