Skip to content

Commit 33441d9

Browse files
NerzalTobias Theel
Nerzal
and
Tobias Theel
authored
Implementing OpenAPI 3.1.0 spec (#1513)
* fix x-tagGroups * fix module name * change paths * refactoring * update dependencies * stuff * add log * fix finding of main file * fix broken type resolution * fix bug * clean deps * fix tool after merging upstream * use json-iterator to marshal json * fix generating of json examples * update config used by jsoniter * bump version * update dependencies * resolve merge conflicts * use newest go in docker * yep * fix gen * fix gen * update swag version * yep * fix parser * fix some tests * fix all tests * parse most of general api description * implement security scheme parsing * parse oauth2 specs * parse scopes and extensions in security schemes * extend parsing security stuff * process v3 routes * meh * find unimported types * parse basic operation info * parse primitive and object parameters * generate openapi spec * fix module name * cleanup * update version to 2.0 * fix issues that appread after merging * cleanup after merge conflicts * fix all tests * add go 1.19 to workflows * pin dockerfile to 1.19.7 * Set minimum supported Go version to 1.18.x * parse response headers * copy readme * started to implement field parser * Refactor: use RefOrSpec instead of Spec * start to add tests for operationv3 * fix tests * implement allOf with primitive types * Add NestedPrimitiveArrayType test * implement TestParseResponseCommentWithNestedFieldsV3 * add more tests * parse arrays and maps * fix implementation of map types * implement more tests * fix example docs * adjust example * fix example jsons * support array types in Parameters * implement more tests, implement correct collectionFormat handling * finish implementation of operationv3 tests * all tests green * fix parsing of security definitions * add test for generalAPI info * end of day checkin * Update example.json * fix codeSamples from file and fix creation of operations * fix resolving of schema ref errors * fix tests that broke due to fixes on model parsing * Fix creating schemes of array types of custom objects * Fix resolution of refSchemas * cleanup * update dependencies * cleanup * Update README.md reset readme.md * Update README_zh-CN.md reset readme_zh-CN * update dependency * reset test file --------- Co-authored-by: Tobias Theel <[email protected]>
1 parent f475da2 commit 33441d9

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+6140
-277
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ jobs:
1010
test:
1111
strategy:
1212
matrix:
13-
go: [ '1.16.x', '1.17.x', '1.18.x' ]
13+
go: [ '1.18.x', '1.19.x', '1.20.x' ]
1414
platform: [ubuntu-latest, macos-latest]
1515
runs-on: ${{ matrix.platform }}
1616
steps:

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,6 @@ cover.out
2020

2121
/swag
2222
/swag.exe
23+
cmd/swag/docs/*
24+
25+
.vscode/launch.json

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Swag converts Go annotations to Swagger Documentation 2.0. We've created a varie
5454
```sh
5555
go install github.com/swaggo/swag/cmd/swag@latest
5656
```
57-
To build from source you need [Go](https://golang.org/dl/) (1.16 or newer).
57+
To build from source you need [Go](https://golang.org/dl/) (1.17 or newer).
5858

5959
Or download a pre-compiled binary from the [release page](https://github.com/swaggo/swag/releases).
6060

‎README_zh-CN.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Swag将Go的注释转换为Swagger2.0文档。我们为流行的 [Go Web Framewo
5050
go install github.com/swaggo/swag/cmd/swag@latest
5151
```
5252

53-
从源码开始构建的话，需要有Go环境（1.16及以上版本）。
53+
从源码开始构建的话，需要有Go环境（1.17及以上版本）。
5454

5555
或者从github的release页面下载预编译好的二进制文件。
5656

‎cmd/swag/main.go‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@ import (
77
"os"
88
"strings"
99

10-
"github.com/urfave/cli/v2"
11-
1210
"github.com/swaggo/swag"
1311
"github.com/swaggo/swag/format"
1412
"github.com/swaggo/swag/gen"
13+
14+
"github.com/urfave/cli/v2"
1515
)
1616

1717
const (
@@ -35,6 +35,7 @@ const (
3535
quietFlag = "quiet"
3636
tagsFlag = "tags"
3737
parseExtensionFlag = "parseExtension"
38+
openAPIVersionFlag = "v3.1"
3839
packageName = "packageName"
3940
collectionFormatFlag = "collectionFormat"
4041
)
@@ -143,6 +144,11 @@ var initFlags = []cli.Flag{
143144
Value: "",
144145
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",
145146
},
147+
&cli.BoolFlag{
148+
Name: openAPIVersionFlag,
149+
Value: false,
150+
Usage: "Generate OpenAPI V3.1 spec",
151+
},
146152
&cli.StringFlag{
147153
Name: packageName,
148154
Value: "",
@@ -201,11 +207,13 @@ func initAction(ctx *cli.Context) error {
201207
Tags: ctx.String(tagsFlag),
202208
PackageName: ctx.String(packageName),
203209
Debugger: logger,
210+
OpenAPIVersion: ctx.Bool(openAPIVersionFlag),
204211
CollectionFormat: collectionFormat,
205212
})
206213
}
207214

208215
func main() {
216+
fmt.Println("Swag version: ", swag.Version)
209217
app := cli.NewApp()
210218
app.Version = swag.Version
211219
app.Usage = "Automatically generate RESTful API documentation with Swagger 2.0 for Go."

‎enums_test.go‎

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,29 @@
11
package swag
22

33
import (
4-
"encoding/json"
5-
"os"
6-
"path/filepath"
74
"testing"
85

96
"github.com/stretchr/testify/assert"
7+
"github.com/stretchr/testify/require"
108
)
119

1210
func TestParseGlobalEnums(t *testing.T) {
1311
searchDir := "testdata/enums"
14-
expected, err := os.ReadFile(filepath.Join(searchDir, "expected.json"))
15-
assert.NoError(t, err)
1612

1713
p := New()
18-
err = p.ParseAPI(searchDir, mainAPIFile, defaultParseDepth)
19-
assert.NoError(t, err)
20-
b, err := json.MarshalIndent(p.swagger, "", " ")
21-
assert.NoError(t, err)
22-
assert.Equal(t, string(expected), string(b))
23-
constsPath := "github.com/swaggo/swag/testdata/enums/consts"
24-
assert.Equal(t, 64, p.packages.packages[constsPath].ConstTable["uintSize"].Value)
25-
assert.Equal(t, int32(62), p.packages.packages[constsPath].ConstTable["maxBase"].Value)
26-
assert.Equal(t, 8, p.packages.packages[constsPath].ConstTable["shlByLen"].Value)
27-
assert.Equal(t, 255, p.packages.packages[constsPath].ConstTable["hexnum"].Value)
28-
assert.Equal(t, 15, p.packages.packages[constsPath].ConstTable["octnum"].Value)
29-
assert.Equal(t, `aa\nbb\u8888cc`, p.packages.packages[constsPath].ConstTable["nonescapestr"].Value)
30-
assert.Equal(t, "aa\nbb\u8888cc", p.packages.packages[constsPath].ConstTable["escapestr"].Value)
31-
assert.Equal(t, '\u8888', p.packages.packages[constsPath].ConstTable["escapechar"].Value)
14+
err := p.ParseAPI(searchDir, mainAPIFile, defaultParseDepth)
15+
require.NoError(t, err)
16+
17+
const constsPath = "github.com/swaggo/swag/testdata/enums/consts"
18+
table := p.packages.packages[constsPath].ConstTable
19+
require.NotNil(t, table, "const table must not be nil")
20+
21+
assert.Equal(t, 64, table["uintSize"].Value)
22+
assert.Equal(t, int32(62), table["maxBase"].Value)
23+
assert.Equal(t, 8, table["shlByLen"].Value)
24+
assert.Equal(t, 255, table["hexnum"].Value)
25+
assert.Equal(t, 15, table["octnum"].Value)
26+
assert.Equal(t, `aa\nbb\u8888cc`, table["nonescapestr"].Value)
27+
assert.Equal(t, "aa\nbb\u8888cc", table["escapestr"].Value)
28+
assert.Equal(t, '\u8888', table["escapechar"].Value)
3229
}

‎example/celler/controller/bottles.go‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ import (
55
"strconv"
66

77
"github.com/gin-gonic/gin"
8-
98
"github.com/swaggo/swag/example/celler/httputil"
109
"github.com/swaggo/swag/example/celler/model"
1110
)

‎example/markdown/go.sum‎

Lines changed: 4 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -67,28 +67,23 @@ github.com/swaggo/swag v1.8.1/go.mod h1:ugemnJsPZm/kRwFUnzBlbHRd0JY9zE1M4F+uy2pA
6767
github.com/urfave/cli/v2 v2.3.0/go.mod h1:LJmUH05zAU44vOAcrfzZQKsZbVcdbOG8rtL3/XcUArI=
6868
github.com/yuin/goldmark v1.4.0/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
6969
github.com/yuin/goldmark v1.4.1/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
70-
github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
7170
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
7271
golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
7372
golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
7473
golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
7574
golang.org/x/mod v0.6.0-dev.0.20220106191415-9b9b3d81d5e3 h1:kQgndtyPBW/JIYERgdxfwMYh3AVStj88WQTlNDi2a+o=
7675
golang.org/x/mod v0.6.0-dev.0.20220106191415-9b9b3d81d5e3/go.mod h1:3p9vT2HGsQu2K1YbXdKPJLVgG5VJdoTa1poYQBtP1AY=
77-
golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4 h1:6zppjxzCulZykYSLyVDYbneBfbaBIQPYMevg0bEwv2s=
78-
golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
7976
golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
8077
golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
8178
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
8279
golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
8380
golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM=
8481
golang.org/x/net v0.0.0-20210805182204-aaa1db679c0d/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
8582
golang.org/x/net v0.0.0-20211015210444-4f30a5c0130f/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
86-
golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
87-
golang.org/x/net v0.7.0 h1:rJrUqqhjsgNp7KqAIc25s9pZnjU7TUcSY7HcVZjdn1g=
88-
golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
83+
golang.org/x/net v0.0.0-20220425223048-2871e0cb64e4 h1:HVyaeDAYux4pnY+D/SiwmLOR36ewZ4iGQIIrtnuCjFA=
84+
golang.org/x/net v0.0.0-20220425223048-2871e0cb64e4/go.mod h1:CfG3xpIq0wQ8r1q4Su4UZFWDARRcnwPjda9FqA0JpMk=
8985
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
9086
golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
91-
golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
9287
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
9388
golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
9489
golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -97,26 +92,20 @@ golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7w
9792
golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
9893
golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
9994
golang.org/x/sys v0.0.0-20211019181941-9d821ace8654/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
100-
golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
101-
golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
102-
golang.org/x/sys v0.5.0 h1:MUK/U/4lj1t1oPg0HfuXDN/Z1wv31ZJ/YcPiGccS4DU=
103-
golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
95+
golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e h1:fLOSk5Q00efkSvAm+4xcoXD+RRmLmmulPn5I3Y9F2EM=
96+
golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
10497
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
10598
golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
106-
golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
10799
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
108100
golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
109101
golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
110102
golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
111-
golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
112103
golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
113104
golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
114105
golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
115106
golang.org/x/tools v0.1.7/go.mod h1:LGqMHiF4EqQNHR1JncWGqT5BVaXmza+X+BDGol+dOxo=
116107
golang.org/x/tools v0.1.10 h1:QjFRCZxdOhBJ/UNgnBZLbNV13DlbnK0quyivTnXJM20=
117108
golang.org/x/tools v0.1.10/go.mod h1:Uh6Zz+xoGYZom868N8YTex3t7RhtHDBrE8Gzo9bV56E=
118-
golang.org/x/tools v0.1.12 h1:VveCTK38A2rkS8ZqFY25HIDFscX5X9OoEhJd3quQmXU=
119-
golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
120109
golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
121110
golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
122111
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 h1:go1bK/D/BFZV2I8cIQd1NKEZ+0owSTG1fDTci4IqFcE=

‎example/markdown/main.go‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,30 @@
11
package main
22

33
import (
4-
"net/http"
5-
64
"github.com/gorilla/mux"
75
httpSwagger "github.com/swaggo/http-swagger"
86
"github.com/swaggo/swag/example/markdown/api"
97
_ "github.com/swaggo/swag/example/markdown/docs"
8+
"net/http"
109
)
1110

12-
// @title Swagger Example API
13-
// @version 1.0
14-
// @description This is a sample server Petstore server.
15-
// @description.markdown
16-
// @termsOfService http://swagger.io/terms/
11+
// @title Swagger Example API
12+
// @version 1.0
13+
// @description This is a sample server Petstore server.
14+
// @description.markdown
15+
// @termsOfService http://swagger.io/terms/
1716

18-
// @contact.name API Support
19-
// @contact.url http://www.swagger.io/support
20-
// @contact.email [email protected]
17+
// @contact.name API Support
18+
// @contact.url http://www.swagger.io/support
19+
// @contact.email [email protected]
2120

22-
// @license.name Apache 2.0
23-
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
21+
// @license.name Apache 2.0
22+
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
2423

25-
// @tag.name admin
26-
// @tag.description.markdown
24+
// @tag.name admin
25+
// @tag.description.markdown
2726

28-
// @BasePath /v2
27+
// @BasePath /v2
2928

3029
func main() {
3130
router := mux.NewRouter()

‎example/object-map-example/go.mod‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,12 @@ require (
2525
github.com/leodido/go-urn v1.2.0 // indirect
2626
github.com/mailru/easyjson v0.7.6 // indirect
2727
github.com/mattn/go-isatty v0.0.12 // indirect
28-
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect
29-
github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742 // indirect
30-
github.com/ugorji/go/codec v1.1.7 // indirect
28+
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
29+
github.com/modern-go/reflect2 v1.0.1 // indirect
30+
github.com/ugorji/go/codec v1.1.13 // indirect
3131
golang.org/x/crypto v0.0.0-20220411220226-7b82a4e95df4 // indirect
3232
golang.org/x/net v0.7.0 // indirect
3333
golang.org/x/sys v0.5.0 // indirect
34-
golang.org/x/tools v0.1.10 // indirect
34+
golang.org/x/tools v0.1.12 // indirect
3535
gopkg.in/yaml.v2 v2.4.0 // indirect
3636
)

0 commit comments

Comments
 (0)