From 14dd310733edd98c106fc291bb1edd852e53d3af Mon Sep 17 00:00:00 2001 From: Aleem Isiaka Date: Thu, 7 Sep 2023 12:45:08 +0100 Subject: [PATCH 1/5] Add supported methods --- swagger.go | 36 +++++++++++++++++++++++++++++++++--- swagger_test.go | 13 +++++++++++++ 2 files changed, 46 insertions(+), 3 deletions(-) diff --git a/swagger.go b/swagger.go index 9206c78..325ccaf 100644 --- a/swagger.go +++ b/swagger.go @@ -1,6 +1,7 @@ package ginSwagger import ( + "fmt" htmlTemplate "html/template" "net/http" "os" @@ -24,6 +25,7 @@ type swaggerConfig struct { DeepLinking bool PersistAuthorization bool Oauth2DefaultClientID string + SupportedSubmitMethods string } // Config stores ginSwagger configuration variables. @@ -37,9 +39,24 @@ type Config struct { DeepLinking bool PersistAuthorization bool Oauth2DefaultClientID string + SupportedSubmitMethods []string +} + +// supportedMethodsToJSArray converts a list of string to valid javascript array as a go string +func supportedMethodsToJSArray(supportedMethods []string) string { + jsStr := "[" + for i, mtd := range supportedMethods { + sep := "," + if i == 0 || i+1 > len(supportedMethods) { + sep = "" + } + jsStr = fmt.Sprintf("%s%s \"%s\"", jsStr, sep, mtd) + } + return fmt.Sprintf("%s]", jsStr) } func (config Config) toSwaggerConfig() swaggerConfig { + return swaggerConfig{ URL: config.URL, DeepLinking: config.DeepLinking, @@ -48,9 +65,10 @@ func (config Config) toSwaggerConfig() swaggerConfig { Oauth2RedirectURL: "`${window.location.protocol}//${window.location.host}$" + "{window.location.pathname.split('/').slice(0, window.location.pathname.split('/').length - 1).join('/')}" + "/oauth2-redirect.html`", - Title: config.Title, - PersistAuthorization: config.PersistAuthorization, - Oauth2DefaultClientID: config.Oauth2DefaultClientID, + Title: config.Title, + PersistAuthorization: config.PersistAuthorization, + Oauth2DefaultClientID: config.Oauth2DefaultClientID, + SupportedSubmitMethods: supportedMethodsToJSArray(config.SupportedSubmitMethods), } } @@ -106,6 +124,14 @@ func Oauth2DefaultClientID(oauth2DefaultClientID string) func(*Config) { } } +// SupportedSubmitMethods set the supported methods that Try It Out could be enabled for. +// The slice can contain any or all of ["get", "put", "post", "delete", "options", "head", "patch", "trace"], +func SupportedSubmitMethods(supportedSubmitMethods []string) func(*Config) { + return func(c *Config) { + c.SupportedSubmitMethods = supportedSubmitMethods + } +} + // WrapHandler wraps `http.Handler` into `gin.HandlerFunc`. func WrapHandler(handler *webdav.Handler, options ...func(*Config)) gin.HandlerFunc { var config = Config{ @@ -117,6 +143,9 @@ func WrapHandler(handler *webdav.Handler, options ...func(*Config)) gin.HandlerF DeepLinking: true, PersistAuthorization: false, Oauth2DefaultClientID: "", + SupportedSubmitMethods: []string{ + "get", "put", "post", "delete", "options", "head", "patch", "trace", + }, } for _, c := range options { @@ -255,6 +284,7 @@ window.onload = function() { url: "{{.URL}}", dom_id: '#swagger-ui', validatorUrl: null, + supportedSubmitMethods: {{.SupportedSubmitMethods}}, oauth2RedirectUrl: {{.Oauth2RedirectURL}}, persistAuthorization: {{.PersistAuthorization}}, presets: [ diff --git a/swagger_test.go b/swagger_test.go index a7a825b..9b5c31e 100644 --- a/swagger_test.go +++ b/swagger_test.go @@ -254,3 +254,16 @@ func TestOauth2DefaultClientID(t *testing.T) { configFunc(&cfg) assert.Equal(t, "", cfg.Oauth2DefaultClientID) } + +func TestSupportedSubmitMethods(t *testing.T) { + var cfg Config + assert.Equal(t, 0, len(cfg.SupportedSubmitMethods)) + + configFunc := SupportedSubmitMethods([]string{"get"}) + configFunc(&cfg) + assert.Equal(t, []string{"get"}, cfg.SupportedSubmitMethods) + + configFunc = SupportedSubmitMethods([]string{}) + configFunc(&cfg) + assert.Equal(t, []string{}, cfg.SupportedSubmitMethods) +} From bdb25bb8372faa59ec23cfe3c25dece33e1cd8ec Mon Sep 17 00:00:00 2001 From: Aleem Isiaka Date: Thu, 7 Sep 2023 12:47:26 +0100 Subject: [PATCH 2/5] Add read me support --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index 7e07033..ff43ee9 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + # gin-swagger gin middleware to automatically generate RESTful API documentation with Swagger 2.0. @@ -15,43 +16,54 @@ gin middleware to automatically generate RESTful API documentation with Swagger 1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format). 2. Download [Swag](https://github.com/swaggo/swag) for Go by using: +--- ```sh go get -u github.com/swaggo/swag/cmd/swag ``` +--- Starting in Go 1.17, installing executables with `go get` is deprecated. `go install` may be used instead: +--- ```sh go install github.com/swaggo/swag/cmd/swag@latest ``` +--- 3. Run the [Swag](https://github.com/swaggo/swag) at your Go project root path(for instance `~/root/go-project-name`), [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`) at `~/root/go-project-name/docs`. +--- ```sh swag init ``` +--- 4. Download [gin-swagger](https://github.com/swaggo/gin-swagger) by using: +--- ```sh go get -u github.com/swaggo/gin-swagger go get -u github.com/swaggo/files ``` +--- Import following in your code: +--- ```go 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: +--- ```go // A get function which returns a hello world string by json func Helloworld(g *gin.Context) { @@ -59,11 +71,13 @@ func Helloworld(g *gin.Context) { } ``` +--- 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: +--- ```go // @BasePath /api/v1 @@ -80,21 +94,25 @@ func Helloworld(g *gin.Context) { g.JSON(http.StatusOK,"helloworld") } ``` +--- 2. Use `swag init` command to generate a docs, docs generated will be stored at `docs/`. 3. import the docs like this: I assume your project named `github.com/go-project-name/docs`. +--- ```go import ( docs "github.com/go-project-name/docs" ) ``` +--- 4. build your application and after that, go to http://localhost:8080/swagger/index.html ,you to see your Swagger UI. 5. The full code and folder relatives here: +--- ```go package main @@ -135,9 +153,11 @@ func main() { } ``` +--- Demo project tree, `swag init` is run at relative `.` +--- ``` . ├── docs @@ -148,6 +168,7 @@ Demo project tree, `swag init` is run at relative `.` ├── go.sum └── main.go ``` +--- ## Multiple APIs @@ -157,6 +178,7 @@ This feature was introduced in swag v1.7.9 You can configure Swagger using different configuration options +--- ```go func main() { r := gin.New() @@ -168,6 +190,7 @@ func main() { r.Run() } ``` +--- | Option | Type | Default | Description | | ------------------------ | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -178,3 +201,4 @@ func main() { | 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_). | | PersistAuthorization | bool | false | If set to true, it persists authorization data and it would not be lost on browser close/refresh. | | Oauth2DefaultClientID | string | "" | If set, it's used to prepopulate the _client_id_ field of the OAuth2 Authorization dialog. | +| SupportedSubmitMethods | []string | ["get", "put", "post", "delete", "options", "head", "patch", "trace"] | This controls the methods that has Try It Out buttons. Set the methods to support or pass an empty string slice to support none | From c09ab37f43bc0ca3c6625e0498aa57f1c4679a96 Mon Sep 17 00:00:00 2001 From: Aleem Isiaka Date: Thu, 7 Sep 2023 13:01:03 +0100 Subject: [PATCH 3/5] Revert readme lines --- README.md | 25 +++---------------------- 1 file changed, 3 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index ff43ee9..c6eb6f4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ - # gin-swagger gin middleware to automatically generate RESTful API documentation with Swagger 2.0. @@ -20,50 +19,43 @@ gin middleware to automatically generate RESTful API documentation with Swagger ```sh go get -u github.com/swaggo/swag/cmd/swag ``` ---- + Starting in Go 1.17, installing executables with `go get` is deprecated. `go install` may be used instead: ---- + ```sh go install github.com/swaggo/swag/cmd/swag@latest ``` ---- + 3. Run the [Swag](https://github.com/swaggo/swag) at your Go project root path(for instance `~/root/go-project-name`), [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`) at `~/root/go-project-name/docs`. ---- ```sh swag init ``` ---- 4. Download [gin-swagger](https://github.com/swaggo/gin-swagger) by using: ---- ```sh go get -u github.com/swaggo/gin-swagger go get -u github.com/swaggo/files ``` ---- Import following in your code: ---- ```go 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: ---- ```go // A get function which returns a hello world string by json func Helloworld(g *gin.Context) { @@ -71,13 +63,11 @@ func Helloworld(g *gin.Context) { } ``` ---- 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: ---- ```go // @BasePath /api/v1 @@ -94,25 +84,21 @@ func Helloworld(g *gin.Context) { g.JSON(http.StatusOK,"helloworld") } ``` ---- 2. Use `swag init` command to generate a docs, docs generated will be stored at `docs/`. 3. import the docs like this: I assume your project named `github.com/go-project-name/docs`. ---- ```go import ( docs "github.com/go-project-name/docs" ) ``` ---- 4. build your application and after that, go to http://localhost:8080/swagger/index.html ,you to see your Swagger UI. 5. The full code and folder relatives here: ---- ```go package main @@ -153,11 +139,9 @@ func main() { } ``` ---- Demo project tree, `swag init` is run at relative `.` ---- ``` . ├── docs @@ -168,7 +152,6 @@ Demo project tree, `swag init` is run at relative `.` ├── go.sum └── main.go ``` ---- ## Multiple APIs @@ -178,7 +161,6 @@ This feature was introduced in swag v1.7.9 You can configure Swagger using different configuration options ---- ```go func main() { r := gin.New() @@ -190,7 +172,6 @@ func main() { r.Run() } ``` ---- | Option | Type | Default | Description | | ------------------------ | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | From 2666b93d7eb00bba53fee5b2df84d599ac671602 Mon Sep 17 00:00:00 2001 From: Aleem Isiaka Date: Thu, 7 Sep 2023 13:01:49 +0100 Subject: [PATCH 4/5] Revert readme lines --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index c6eb6f4..b210869 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,6 @@ gin middleware to automatically generate RESTful API documentation with Swagger 1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format). 2. Download [Swag](https://github.com/swaggo/swag) for Go by using: ---- ```sh go get -u github.com/swaggo/swag/cmd/swag ``` From 977e936e16e5a7ae934ddc153f726a0f44959625 Mon Sep 17 00:00:00 2001 From: Aleem Isiaka Date: Thu, 7 Sep 2023 13:02:35 +0100 Subject: [PATCH 5/5] Revert readme lines --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index b210869..beb32e0 100644 --- a/README.md +++ b/README.md @@ -19,15 +19,12 @@ gin middleware to automatically generate RESTful API documentation with Swagger go get -u github.com/swaggo/swag/cmd/swag ``` - Starting in Go 1.17, installing executables with `go get` is deprecated. `go install` may be used instead: - ```sh go install github.com/swaggo/swag/cmd/swag@latest ``` - 3. Run the [Swag](https://github.com/swaggo/swag) at your Go project root path(for instance `~/root/go-project-name`), [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`) at `~/root/go-project-name/docs`.