Merge branch 'v2' into v2-merge

.gitignore

@@ -22,3 +22,6 @@ cover.out
 
 /swag
 /swag.exe
+cmd/swag/docs/*
+
+.vscode/launch.json

Makefile

@@ -14,7 +14,7 @@ GOPATH:=$(shell $(GOCMD) env GOPATH)
 u := $(if $(update),-u)
 
 BINARY_NAME:=swag
-PACKAGES:=$(shell $(GOLIST) github.com/swaggo/swag github.com/swaggo/swag/cmd/swag github.com/swaggo/swag/gen github.com/swaggo/swag/format)
+PACKAGES:=$(shell $(GOLIST) github.com/swaggo/swag/v2 github.com/swaggo/swag/v2/cmd/swag github.com/swaggo/swag/v2/gen github.com/swaggo/swag/v2/format)
 GOFILES:=$(shell find . -name "*.go" -type f)
 
 all: test build

README.md

@@ -17,44 +17,61 @@
 Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular [Go web frameworks](#supported-web-frameworks). This allows you to quickly integrate with an existing Go project (using Swagger UI).
 
 ## Contents
- - [Getting started](#getting-started)
- - [Supported Web Frameworks](#supported-web-frameworks)
- - [How to use it with Gin](#how-to-use-it-with-gin)
- - [The swag formatter](#the-swag-formatter)
- - [Implementation Status](#implementation-status)
- - [Declarative Comments Format](#declarative-comments-format)
-	- [General API Info](#general-api-info)
-	- [API Operation](#api-operation)
-	- [Security](#security)
- - [Examples](#examples)
-	- [Descriptions over multiple lines](#descriptions-over-multiple-lines)
-	- [User defined structure with an array type](#user-defined-structure-with-an-array-type)
-	- [Function scoped struct declaration](#function-scoped-struct-declaration)
-	- [Model composition in response](#model-composition-in-response)
-        - [Add request headers](#add-request-headers)
-	- [Add response headers](#add-response-headers)
-	- [Use multiple path params](#use-multiple-path-params)
-	- [Example value of struct](#example-value-of-struct)
-	- [SchemaExample of body](#schemaexample-of-body)
-	- [Description of struct](#description-of-struct)
-	- [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type)
-	- [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type)
-	- [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field)
-	- [Add extension info to struct field](#add-extension-info-to-struct-field)
-	- [Rename model to display](#rename-model-to-display)
-	- [How to use security annotations](#how-to-use-security-annotations)
-	- [Add a description for enum items](#add-a-description-for-enum-items)
-	- [Generate only specific docs file types](#generate-only-specific-docs-file-types)
-    - [How to use Go generic types](#how-to-use-generics)
-- [About the Project](#about-the-project)
+- [swag](#swag)
+  - [Contents](#contents)
+  - [Getting started](#getting-started)
+  - [swag cli](#swag-cli)
+  - [Supported Web Frameworks](#supported-web-frameworks)
+  - [How to use it with Gin](#how-to-use-it-with-gin)
+  - [The swag formatter](#the-swag-formatter)
+  - [Implementation Status](#implementation-status)
+- [Declarative Comments Format](#declarative-comments-format)
+  - [General API Info](#general-api-info)
+    - [Using markdown descriptions](#using-markdown-descriptions)
+  - [Open API V3.1.0+](#open-api-v310)
+  - [API Operation](#api-operation)
+  - [Mime Types](#mime-types)
+  - [Param Type](#param-type)
+  - [Data Type](#data-type)
+  - [Security](#security)
+  - [Attribute](#attribute)
+    - [Available](#available)
+    - [Future](#future)
+  - [Examples](#examples)
+    - [Descriptions over multiple lines](#descriptions-over-multiple-lines)
+    - [User defined structure with an array type](#user-defined-structure-with-an-array-type)
+    - [Function scoped struct declaration](#function-scoped-struct-declaration)
+    - [Model composition in response](#model-composition-in-response)
+    - [Add headers in request](#add-request-headers)
+    - [Add headers in response](#add-a-headers-in-response)
+    - [Use multiple path params](#use-multiple-path-params)
+    - [Add multiple paths](#add-multiple-paths)
+    - [Example value of struct](#example-value-of-struct)
+    - [SchemaExample of body](#schemaexample-of-body)
+    - [Description of struct](#description-of-struct)
+    - [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type)
+    - [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type)
+    - [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field)
+    - [Add extension info to struct field](#add-extension-info-to-struct-field)
+    - [Rename model to display](#rename-model-to-display)
+    - [How to use security annotations](#how-to-use-security-annotations)
+    - [Add a description for enum items](#add-a-description-for-enum-items)
+    - [Generate only specific docs file types](#generate-only-specific-docs-file-types)
+        - [How to use Go generic types](#how-to-use-generics)
+    - [Change the default Go Template action delimiters](#change-the-default-go-template-action-delimiters)
+  - [About the Project](#about-the-project)
+  - [Contributors](#contributors)
+  - [Backers](#backers)
+  - [Sponsors](#sponsors)
+  - [License](#license)
 
 ## Getting started
 
 1. Add comments to your API source code, See [Declarative Comments Format](#declarative-comments-format).
 
 2. Install swag by using:
 ```sh
-go install github.com/swaggo/swag/cmd/swag@latest
+go install github.com/swaggo/swag/v2/cmd/swag@latest
 ```
 To build from source you need [Go](https://golang.org/dl/) (1.19 or newer).
 
@@ -88,6 +105,7 @@ swag init
 
 ```sh
 swag init -h
+Swag version:  v2.0.0
 NAME:
    swag init - Create docs.go
 
@@ -114,12 +132,16 @@ OPTIONS:
    --instanceName value                   This parameter can be used to name different swagger document instances. It is optional.
    --overridesFile value                  File to read global type overrides from. (default: ".swaggo")
    --parseGoList                          Parse dependency via 'go list' (default: true)
+   --parseExtension value                 Parse only those operations that match given extension
    --tags value, -t value                 A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the '!' character then the APIs with that tag will be excluded
-   --templateDelims value, --td value     Provide custom delimiters for Go template generation. The format is leftDelim,rightDelim. For example: "[[,]]"
+   --v3.1                                 Generate OpenAPI V3.1 spec (default: false)
+   --templateDelims value, --td value     Provide custom delimeters for Go template generation. The format is leftDelim,rightDelim. For example: "[[,]]"
    --collectionFormat value, --cf value   Set default collection format (default: "csv")
    --state value                          Initial state for the state machine (default: ""), @HostState in root file, @State in other files
    --parseFuncBody                        Parse API info within body of functions in go files, disabled by default (default: false)
-   --help, -h                             show help (default: false)
+   --packageName --output                 A package name of docs.go, using output directory name by default (check --output option)
+   --collectionFormat value, --cf value   Set default collection format (default: "csv")
+   --help, -h                             show help
 ```
 
 ```bash
@@ -421,6 +443,14 @@ When a short string in your documentation is insufficient, or you need images, c
 | tag.name    | Name of a tag.| // @tag.name This is the name of the tag                     |
 | tag.description.markdown   | Description of the tag this is an alternative to tag.description. The description will be read from a file named like tagname.md  | // @tag.description.markdown         |
 
+## Open API V3.1.0+
+
+The following annotations are only available if you set the -v3.1 flag in the CLI.
+
+| annotation  | description                                | example                         |
+|-------------|--------------------------------------------|---------------------------------|
+| servers.url       | The URL of a server| // @servers.url https://petstore.example.com/api/v1   |
+| servers.description       | The description of a server| // @servers.description Production API   |
 
 ## API Operation
 
@@ -493,12 +523,13 @@ Besides that, `swag` also accepts aliases for some MIME Types as follows:
 ## Security
 | annotation | description | parameters | example |
 |------------|-------------|------------|---------|
-| securitydefinitions.basic  | [Basic](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth.  |                                   | // @securityDefinitions.basic BasicAuth                      |
-| securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth.            | in, name, description                          | // @securityDefinitions.apikey ApiKeyAuth                    |
-| securitydefinitions.oauth2.application  | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth.       | tokenUrl, scope, description                   | // @securitydefinitions.oauth2.application OAuth2Application |
-| securitydefinitions.oauth2.implicit     | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth.          | authorizationUrl, scope, description           | // @securitydefinitions.oauth2.implicit OAuth2Implicit       |
-| securitydefinitions.oauth2.password     | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth.          | tokenUrl, scope, description                   | // @securitydefinitions.oauth2.password OAuth2Password       |
-| securitydefinitions.oauth2.accessCode   | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth.       | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode   |
+| securitydefinitions.basic               | [Basic](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth.             |                                                | // @securityDefinitions.basic BasicAuth                      |
+| securitydefinitions.apikey              | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth.                       | in, name, description                          | // @securityDefinitions.apikey ApiKeyAuth                    |
+| securitydefinitions.oauth2.application  | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth.                  | tokenUrl, scope, description                   | // @securitydefinitions.oauth2.application OAuth2Application |
+| securitydefinitions.oauth2.implicit     | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth.                     | authorizationUrl, scope, description           | // @securitydefinitions.oauth2.implicit OAuth2Implicit       |
+| securitydefinitions.oauth2.password     | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth.                     | tokenUrl, scope, description                   | // @securitydefinitions.oauth2.password OAuth2Password       |
+| securitydefinitions.oauth2.accessCode   | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth.                  | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode   |
+| securitydefinitions.bearerauth          | [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) auth. supported in Swagger v3.x|                                                | // @securitydefinitions.bearerauth BearerAuth                |
 
 
 | parameters annotation           | example                                                                 |

cmd/swag/main.go

@@ -7,11 +7,11 @@ import (
 	"os"
 	"strings"
 
-	"github.com/urfave/cli/v2"
+	"github.com/swaggo/swag/v2"
+	"github.com/swaggo/swag/v2/format"
+	"github.com/swaggo/swag/v2/gen"
 
-	"github.com/swaggo/swag"
-	"github.com/swaggo/swag/format"
-	"github.com/swaggo/swag/gen"
+	"github.com/urfave/cli/v2"
 )
 
 const (
@@ -38,6 +38,7 @@ const (
 	tagsFlag                 = "tags"
 	parseExtensionFlag       = "parseExtension"
 	templateDelimsFlag       = "templateDelims"
+ 	openAPIVersionFlag       = "v3.1"
 	packageName              = "packageName"
 	collectionFormatFlag     = "collectionFormat"
 	packagePrefixFlag        = "packagePrefix"
@@ -154,6 +155,17 @@ var initFlags = []cli.Flag{
 		Value:   "",
 		Usage:   "A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the '!' character then the APIs with that tag will be excluded",
 	},
+	&cli.BoolFlag{
+		Name:  openAPIVersionFlag,
+		Value: false,
+		Usage: "Generate OpenAPI V3.1 spec",
+	},
+	&cli.StringFlag{
+		Name:    templateDelimsFlag,
+		Aliases: []string{"td"},
+		Value:   "",
+		Usage:   "Provide custom delimeters for Go template generation. The format is leftDelim,rightDelim. For example: \"[[,]]\"",
+	},
 	&cli.StringFlag{
 		Name:    templateDelimsFlag,
 		Aliases: []string{"td"},
@@ -264,6 +276,7 @@ func initAction(ctx *cli.Context) error {
 		RightTemplateDelim:  rightDelim,
 		PackageName:         ctx.String(packageName),
 		Debugger:            logger,
+		GenerateOpenAPI3Doc: ctx.Bool(openAPIVersionFlag),
 		CollectionFormat:    collectionFormat,
 		PackagePrefix:       ctx.String(packagePrefixFlag),
 		State:               ctx.String(stateFlag),
@@ -272,6 +285,7 @@ func initAction(ctx *cli.Context) error {
 }
 
 func main() {
+	fmt.Println("Swag version: ", swag.Version)
 	app := cli.NewApp()
 	app.Version = swag.Version
 	app.Usage = "Automatically generate RESTful API documentation with Swagger 2.0 for Go."

doc.go

@@ -2,4 +2,4 @@
 Package swag converts Go annotations to Swagger Documentation 2.0.
 See https://github.com/swaggo/swag for more information about swag.
 */
-package swag // import "github.com/swaggo/swag"
+package swag // import "github.com/swaggo/swag/v2"

enums_test.go

@@ -1,27 +1,30 @@
 package swag
 
 import (
+
 	"encoding/json"
 	"math/bits"
 	"os"
 	"path/filepath"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestParseGlobalEnums(t *testing.T) {
 	searchDir := "testdata/enums"
-	expected, err := os.ReadFile(filepath.Join(searchDir, "expected.json"))
-	assert.NoError(t, err)
 
 	p := New()
 	err = p.ParseAPI(searchDir, mainAPIFile, defaultParseDepth)
 	assert.NoError(t, err)
+
 	b, err := json.MarshalIndent(p.swagger, "", "    ")
 	assert.NoError(t, err)
 	assert.Equal(t, string(expected), string(b))
-	constsPath := "github.com/swaggo/swag/testdata/enums/consts"
+
+	constsPath := "github.com/swaggo/swag/v2/testdata/enums/consts"
+
 	assert.Equal(t, bits.UintSize, p.packages.packages[constsPath].ConstTable["uintSize"].Value)
 	assert.Equal(t, int32(62), p.packages.packages[constsPath].ConstTable["maxBase"].Value)
 	assert.Equal(t, 8, p.packages.packages[constsPath].ConstTable["shlByLen"].Value)
@@ -31,4 +34,5 @@ func TestParseGlobalEnums(t *testing.T) {
 	assert.Equal(t, "aa\nbb\u8888cc", p.packages.packages[constsPath].ConstTable["escapestr"].Value)
 	assert.Equal(t, 1_000_000, p.packages.packages[constsPath].ConstTable["underscored"].Value)
 	assert.Equal(t, 0b10001000, p.packages.packages[constsPath].ConstTable["binaryInteger"].Value)
+
 }

example/basic/api/api.go

@@ -4,7 +4,7 @@ import (
 	"encoding/json"
 	"net/http"
 
-	"github.com/swaggo/swag/example/basic/web"
+	"github.com/swaggo/swag/v2/example/basic/web"
 )
 
 // GetStringByInt example

example/basic/docs/docs.go

@@ -2,7 +2,7 @@
 // This file was generated by swaggo/swag
 package docs
 
-import "github.com/swaggo/swag"
+import "github.com/swaggo/swag/v2"
 
 const docTemplate = `{
     "schemes": {{ marshal .Schemes }},

example/basic/main.go

@@ -3,7 +3,7 @@ package main
 import (
 	"net/http"
 
-	"github.com/swaggo/swag/example/basic/api"
+	"github.com/swaggo/swag/v2/example/basic/api"
 )
 
 //	@title			Swagger Example API

example/celler/controller/accounts.go

@@ -6,8 +6,8 @@ import (
 	"strconv"
 
 	"github.com/gin-gonic/gin"
-	"github.com/swaggo/swag/example/celler/httputil"
-	"github.com/swaggo/swag/example/celler/model"
+	"github.com/swaggo/swag/v2/example/celler/httputil"
+	"github.com/swaggo/swag/v2/example/celler/model"
 )
 
 // ShowAccount godoc

example/celler/controller/admin.go

@@ -6,8 +6,8 @@ import (
 	"net/http"
 
 	"github.com/gin-gonic/gin"
-	"github.com/swaggo/swag/example/celler/httputil"
-	"github.com/swaggo/swag/example/celler/model"
+	"github.com/swaggo/swag/v2/example/celler/httputil"
+	"github.com/swaggo/swag/v2/example/celler/model"
 )
 
 // Auth godoc

example/celler/controller/bottles.go

@@ -5,9 +5,8 @@ import (
 	"strconv"
 
 	"github.com/gin-gonic/gin"
-
-	"github.com/swaggo/swag/example/celler/httputil"
-	"github.com/swaggo/swag/example/celler/model"
+	"github.com/swaggo/swag/v2/example/celler/httputil"
+	"github.com/swaggo/swag/v2/example/celler/model"
 )
 
 // ShowBottle godoc

example/celler/controller/examples.go

@@ -6,7 +6,7 @@ import (
 	"strconv"
 
 	"github.com/gin-gonic/gin"
-	"github.com/swaggo/swag/example/celler/httputil"
+	"github.com/swaggo/swag/v2/example/celler/httputil"
 )
 
 // PingExample godoc

example/celler/go.mod

@@ -7,7 +7,7 @@ require (
 	github.com/gofrs/uuid v4.2.0+incompatible
 	github.com/swaggo/files v0.0.0-20210815190702-a29dd2bc99b2
 	github.com/swaggo/gin-swagger v1.4.2
-	github.com/swaggo/swag v1.8.1
+	github.com/swaggo/swag/v2 v2.0.0-beta
 )
 
 require (

example/celler/main.go

@@ -5,9 +5,9 @@ import (
 	"net/http"
 
 	"github.com/gin-gonic/gin"
-	"github.com/swaggo/swag/example/celler/controller"
-	_ "github.com/swaggo/swag/example/celler/docs"
-	"github.com/swaggo/swag/example/celler/httputil"
+	"github.com/swaggo/swag/v2/example/celler/controller"
+	_ "github.com/swaggo/swag/v2/example/celler/docs"
+	"github.com/swaggo/swag/v2/example/celler/httputil"
 
 	swaggerFiles "github.com/swaggo/files"
 	ginSwagger "github.com/swaggo/gin-swagger"

example/markdown/docs/docs.go

@@ -2,7 +2,7 @@
 // This file was generated by swaggo/swag
 package docs
 
-import "github.com/swaggo/swag"
+import "github.com/swaggo/swag/v2"
 
 const docTemplate = `{
     "schemes": {{ marshal .Schemes }},