ginSwagger

package module
Version: v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 6, 2022 License: MIT Imports: 9 Imported by: 665

README

gin-swagger

gin middleware to automatically generate RESTFUL API documentation with Swagger 2.0.

Build Status Codecov branch Go Report Card GoDoc Release

Usage

Start using it
  1. Add comments to your API source code, See Declarative Comments Format.
  2. Download Swag for Go by using:
go get -u github.com/swaggo/swag/cmd/swag
  1. Run the Swag at your Go project root path(for instance ~/root/go-peoject-name), Swag will parse comments and generate required files(docs folder and docs/doc.go) at ~/root/go-peoject-name/docs.
swag init
  1. Download gin-swagger by using:
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

Import following in your code:

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files

Canonical example:

Now assume you have implemented a simple api as following:

// A get function which returns a hello world string by json
func Helloworld(g *gin.Context)  {
	g.JSON(http.StatusOK,"helloworld")
}

So how to use gin-swagger on api above? Just follow the following guide.

  1. Add Comments for apis and main function with gin-swagger rules like following:
// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
	g.JSON(http.StatusOK,"helloworld")
}
  1. Use swag init command to generate a docs, docs generated will be stored at docs/.
  2. import the docs like this: I assume your project named github.com/go-project-name/docs.
import (
   docs "github.com/go-project-name/docs"
)
  1. build your application and after that, go to http://localhost:8080/swagger/index.html ,you to see your Swagger UI.

  2. The full code and folder relatives here:

package main

import (
   "github.com/gin-gonic/gin"
   docs "github.com/go-project-name/docs"
   swaggerfiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
   "net/http"
)
// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
   g.JSON(http.StatusOK,"helloworld")
}

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("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
   r.Run(":8080")

}

Demo project tree, swag init is run at relative .

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

Configuration

You can configure Swagger using different configuration options

func main() {
	r := gin.New()

	ginSwagger.WrapHandler(swaggerFiles.Handler,
		ginSwagger.URL("http://localhost:8080/swagger/doc.json"),
		ginSwagger.DefaultModelsExpandDepth(-1))

	r.Run()
}
Option Type Default Description
URL string "doc.json" URL pointing to API definition
DocExpantion string "list" Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing).
DeepLinking bool true If set to true, enables deep linking for tags and operations. See the Deep Linking documentation for more information.
DefaultModelsExpandDepth int 1 Default expansion depth for models (set to -1 completely hide the models).
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).
PersistAuthotization bool false If set to true, it persists authorization data and it would not be lost on browser close/refresh.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CustomWrapHandler added in v1.2.0

func CustomWrapHandler(config *Config, handler *webdav.Handler) gin.HandlerFunc

CustomWrapHandler wraps `http.Handler` into `gin.HandlerFunc`

func DeepLinking added in v1.3.0

func DeepLinking(deepLinking bool) func(c *Config)

DeepLinking set the swagger deeplinking configuration

func DefaultModelsExpandDepth added in v1.3.2

func DefaultModelsExpandDepth(depth int) func(c *Config)

DefaultModelsExpandDepth set the default expansion depth for models (set to -1 completely hide the models).

func DisablingCustomWrapHandler added in v1.2.0

func DisablingCustomWrapHandler(config *Config, h *webdav.Handler, envName string) gin.HandlerFunc

DisablingCustomWrapHandler turn handler off if specified environment variable passed

func DisablingWrapHandler added in v1.1.0

func DisablingWrapHandler(h *webdav.Handler, envName string) gin.HandlerFunc

DisablingWrapHandler turn handler off if specified environment variable passed

func DocExpansion added in v1.3.2

func DocExpansion(docExpansion string) func(c *Config)

DocExpansion list, full, none.

func InstanceName added in v1.3.3

func InstanceName(name string) func(c *Config)

InstanceName set the instance name that was used to generate the swagger documents. Defaults to swag.Name ("swagger").

func PersistAuthorization added in v1.4.1

func PersistAuthorization(persistAuthorization bool) func(c *Config)

If set to true, it persists authorization data and it would not be lost on browser close/refresh Defaults to false

func URL added in v1.2.0

func URL(url string) func(c *Config)

URL presents the url pointing to API definition (normally swagger.json or swagger.yaml).

func WrapHandler

func WrapHandler(h *webdav.Handler, confs ...func(c *Config)) gin.HandlerFunc

WrapHandler wraps `http.Handler` into `gin.HandlerFunc`.

Types

type Config added in v1.2.0

type Config struct {
	//The url pointing to API definition (normally swagger.json or swagger.yaml). Default is `doc.json`.
	URL                      string
	DeepLinking              bool
	DocExpansion             string
	DefaultModelsExpandDepth int
	InstanceName             string
	Title                    string
	PersistAuthorization     bool
}

Config stores ginSwagger configuration variables.

func (Config) ToSwaggerConfig added in v1.3.3

func (c Config) ToSwaggerConfig() swaggerConfig

Convert the config to a swagger one in order to fill unexposed template values.

Source Files

Directories

Path Synopsis
example
basic/docs
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag
gzipped/docs
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL