add support github.com/swaggo/swag/v2

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
   test:
     strategy:
       matrix:
-        go: [ '1.17.x', '1.18.x', '1.19.x','1.20.x' ]
+        go: [ '1.21.x', '1.22.x', '1.23.x' ]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@master

README.md

@@ -7,34 +7,42 @@ echo middleware to automatically generate RESTful API documentation with Swagger
 [![Go Report Card](https://goreportcard.com/badge/github.com/swaggo/echo-swagger)](https://goreportcard.com/report/github.com/swaggo/echo-swagger)
 [![Release](https://img.shields.io/github/release/swaggo/echo-swagger.svg?style=flat-square)](https://github.com/swaggo/echo-swagger/releases)
 
-
 ## Usage
 
 ### Start using it
+
 1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag#declarative-comments-format).
 2. Download [Swag](https://github.com/swaggo/swag) for Go by using:
+
 ```sh
 $ go get -d github.com/swaggo/swag/cmd/swag
 
-# 1.16 or newer
+# 1.21 or newer
 $ go install github.com/swaggo/swag/cmd/swag@latest
 ```
+
 3. Run the [Swag](https://github.com/swaggo/swag) in your Go project root folder which contains `main.go` file, [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`).
+
 ```sh_ "github.com/swaggo/echo-swagger/v2/example/docs"
 $ swag init
 ```
+
 4. Download [echo-swagger](https://github.com/swaggo/echo-swagger) by using:
+
 ```sh
 $ go get -u github.com/swaggo/echo-swagger
 ```
 
 And import following in your code:
+
 ```go
 import "github.com/swaggo/echo-swagger" // echo-swagger middleware
 ```
 
 ### Canonical example:
 
+## OpenAPI Specification (OAS) 2.0
+
 ```go
 package main
 
@@ -66,7 +74,41 @@ func main() {
 
 	e.Logger.Fatal(e.Start(":1323"))
 }
+```
+
+## OpenAPI Specification (OAS) 3.0
+
+```go
+package main
+
+import (
+	"github.com/labstack/echo/v4"
+	"github.com/swaggo/echo-swagger"
+
+	_ "github.com/swaggo/echo-swagger/example/docs" // docs is generated by Swag CLI, you have to import it.
+)
 
+// @title Swagger Example API
+// @version 1.0
+// @description This is a sample server Petstore server.
+// @termsOfService http://swagger.io/terms/
+
+// @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
+
+// @host petstore.swagger.io
+// @BasePath /v2
+func main() {
+	e := echo.New()
+
+	e.GET("/swagger/*", echoSwagger.WrapHandlerV3)
+
+	e.Logger.Fatal(e.Start(":1323"))
+}
 ```
 
 5. Run it, and browser to http://localhost:1323/swagger/index.html, you can see Swagger 2.0 Api documents.

example/docs/docs.go → example/v2/docs/docs.go

@@ -41,4 +41,4 @@ var SwaggerInfo_swagger = &swag.Spec{
 
 func init() {
 	swag.Register(SwaggerInfo_swagger.InstanceName(), SwaggerInfo_swagger)
-}
+}

example/v2/go.mod

@@ -0,0 +1,38 @@
+module github.com/swaggo/echo-swagger/example/v2
+
+go 1.17
+
+replace github.com/swaggo/echo-swagger => ../../
+
+require (
+	github.com/labstack/echo/v4 v4.13.3
+	github.com/swaggo/echo-swagger v0.0.0-00010101000000-000000000000
+	github.com/swaggo/swag v1.16.2
+)
+
+require (
+	github.com/KyleBanks/depth v1.2.1 // indirect
+	github.com/go-openapi/jsonpointer v0.19.6 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/spec v0.20.9 // indirect
+	github.com/go-openapi/swag v0.22.3 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/labstack/gommon v0.4.2 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/sv-tools/openapi v0.2.1 // indirect
+	github.com/swaggo/files/v2 v2.0.0 // indirect
+	github.com/swaggo/swag/v2 v2.0.0-rc4 // indirect
+	github.com/valyala/bytebufferpool v1.0.0 // indirect
+	github.com/valyala/fasttemplate v1.2.2 // indirect
+	golang.org/x/crypto v0.31.0 // indirect
+	golang.org/x/net v0.33.0 // indirect
+	golang.org/x/sys v0.28.0 // indirect
+	golang.org/x/text v0.21.0 // indirect
+	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	sigs.k8s.io/yaml v1.3.0 // indirect
+)

example/main.go → example/v2/main.go

@@ -2,8 +2,8 @@ package main
 
 import (
 	"github.com/labstack/echo/v4"
-	"github.com/swaggo/echo-swagger"
-	_ "github.com/swaggo/echo-swagger/example/docs" // docs is generated by Swag CLI, you have to import it.
+	echoSwagger "github.com/swaggo/echo-swagger"
+	_ "github.com/swaggo/echo-swagger/example/v2/docs" // docs is generated by Swag CLI, you have to import it.
 )
 
 // @title Swagger Example API

example/v3/docs/swagger.json

@@ -0,0 +1 @@
+{"swagger":"2.0","info":{"description":"This is a sample server Petstore server.","title":"Swagger Example API","termsOfService":"http://swagger.io/terms/","contact":{"name":"API Support","url":"http://www.swagger.io/support","email":"[email protected]"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"},"version":"1.0"},"host":"petstore.swagger.io","basePath":"/v2","paths":{}}

example/v3/docs/swagger.yaml

@@ -0,0 +1,16 @@
+basePath: /v2
+host: petstore.swagger.io
+info:
+  contact:
+    email: [email protected]
+    name: API Support
+    url: http://www.swagger.io/support
+  description: This is a sample server Petstore server.
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  termsOfService: http://swagger.io/terms/
+  title: Swagger Example API
+  version: "1.0"
+paths: {}
+swagger: "2.0"

example/v3/go.mod

@@ -0,0 +1,38 @@
+module github.com/swaggo/echo-swagger/example/v3
+
+go 1.17
+
+replace github.com/swaggo/echo-swagger => ../../
+
+require (
+	github.com/labstack/echo/v4 v4.13.3
+	github.com/swaggo/echo-swagger v0.0.0-00010101000000-000000000000
+	github.com/swaggo/swag/v2 v2.0.0-rc4
+)
+
+require (
+	github.com/KyleBanks/depth v1.2.1 // indirect
+	github.com/go-openapi/jsonpointer v0.19.6 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/spec v0.20.9 // indirect
+	github.com/go-openapi/swag v0.22.3 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/labstack/gommon v0.4.2 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/sv-tools/openapi v0.2.1 // indirect
+	github.com/swaggo/files/v2 v2.0.0 // indirect
+	github.com/swaggo/swag v1.16.2 // indirect
+	github.com/valyala/bytebufferpool v1.0.0 // indirect
+	github.com/valyala/fasttemplate v1.2.2 // indirect
+	golang.org/x/crypto v0.31.0 // indirect
+	golang.org/x/net v0.33.0 // indirect
+	golang.org/x/sys v0.28.0 // indirect
+	golang.org/x/text v0.21.0 // indirect
+	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	sigs.k8s.io/yaml v1.3.0 // indirect
+)