Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

License

NotificationsYou must be signed in to change notification settings

molior-dbs/golang-github-swaggo-gin-swagger

Repository files navigation

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

Build StatusCodecov branchGo Report CardGoDocRelease

Usage

Start using it

  1. Add comments to your API source code,See Declarative Comments Format.
  2. DownloadSwag for Go by using:
go get -u github.com/swaggo/swag/cmd/swag

Starting in Go 1.17, installing executables withgo get is deprecated.go install may be used instead:

go install github.com/swaggo/swag/cmd/swag@latest
  1. Run theSwag at your Go project root path(for instance~/root/go-project-name),Swag will parse comments and generate required files(docs folder anddocs/doc.go)at~/root/go-project-name/docs.
swag init
  1. Downloadgin-swagger by using:
go get -u github.com/swaggo/gin-swaggergo get -u github.com/swaggo/files

Import following in your code:

import"github.com/swaggo/gin-swagger"// gin-swagger middlewareimport"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 jsonfuncHelloworld(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]funcHelloworld(g*gin.Context)  {g.JSON(http.StatusOK,"helloworld")}
  1. Useswag init command to generate a docs, docs generated will be stored atdocs/.
  2. import the docs like this:I assume your project namedgithub.com/go-project-name/docs.
import (   docs"github.com/go-project-name/docs")

  1. build your application and after that, go tohttp://localhost:8080/swagger/index.html ,you to see your Swagger UI.

  2. The full code and folder relatives here:

package mainimport ("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]funcHelloworld(g*gin.Context)  {g.JSON(http.StatusOK,"helloworld")}funcmain()  {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

Multiple APIs

This feature was introduced in swag v1.7.9

Configuration

You can configure Swagger using different configuration options

funcmain() {r:=gin.New()ginSwagger.WrapHandler(swaggerfiles.Handler,ginSwagger.URL("http://localhost:8080/swagger/doc.json"),ginSwagger.DefaultModelsExpandDepth(-1))r.Run()}
OptionTypeDefaultDescription
URLstring"doc.json"URL pointing to API definition
DocExpansionstring"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).
DeepLinkingbooltrueIf set to true, enables deep linking for tags and operations. See the Deep Linking documentation for more information.
DefaultModelsExpandDepthint1Default expansion depth for models (set to -1 completely hide the models).
InstanceNamestring"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 withswag init).
PersistAuthorizationboolfalseIf set to true, it persists authorization data and it would not be lost on browser close/refresh.
Oauth2DefaultClientIDstring""If set, it's used to prepopulate theclient_id field of the OAuth2 Authorization dialog.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

[8]ページ先頭
©2009-2025 Movatter.jp