Skip to content

Commit 0fb6820

Browse files
sdghchjsdghchj
authoredJan 11, 2024
deprecate some parts of routers in an operation (#1735)
Signed-off-by: sdghchj <sdghchj@qq.com>
·
v2.0.0-rc4v1.16.3
1 parent 33da992 commit 0fb6820

File tree

8 files changed

+164
-36
lines changed

8 files changed

+164
-36
lines changed
 

‎README.md

+20-19
Original file line numberDiff line numberDiff line change
@@ -425,25 +425,26 @@ When a short string in your documentation is insufficient, or you need images, c
425425
[celler/controller](https://github.com/swaggo/swag/tree/master/example/celler/controller)
426426
427427
428-
| annotation | description |
429-
|-------------|----------------------------------------------------------------------------------------------------------------------------|
430-
| description | A verbose explanation of the operation behavior. |
431-
| description.markdown | A short description of the application. The description will be read from a file. E.g. `@description.markdown details` will load `details.md`| // @description.file endpoint.description.markdown |
432-
| id | A unique string used to identify the operation. Must be unique among all API operations. |
433-
| tags | A list of tags to each API operation that separated by commas. |
434-
| summary | A short summary of what the operation does. |
435-
| accept | A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under [Mime Types](#mime-types). |
436-
| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). |
437-
| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` |
438-
| security | [Security](#security) to each API operation. |
439-
| success | Success response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment` |
440-
| failure | Failure response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment` |
441-
| response | As same as `success` and `failure` |
442-
| header | Header in response that separated by spaces. `return code`,`{param type}`,`data type`,`comment` |
443-
| router | Path definition that separated by spaces. `path`,`[httpMethod]` |
444-
| x-name | The extension key, must be start by x- and take only json value. |
445-
| x-codeSample | Optional Markdown usage. take `file` as parameter. This will then search for a file named like the summary in the given folder. |
446-
| deprecated | Mark endpoint as deprecated. |
428+
| annotation | description |
429+
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
430+
| description | A verbose explanation of the operation behavior. |
431+
| description.markdown | A short description of the application. The description will be read from a file. E.g. `@description.markdown details` will load `details.md` | // @description.file endpoint.description.markdown |
432+
| id | A unique string used to identify the operation. Must be unique among all API operations. |
433+
| tags | A list of tags to each API operation that separated by commas. |
434+
| summary | A short summary of what the operation does. |
435+
| accept | A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under [Mime Types](#mime-types). |
436+
| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). |
437+
| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` |
438+
| security | [Security](#security) to each API operation. |
439+
| success | Success response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment` |
440+
| failure | Failure response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment` |
441+
| response | As same as `success` and `failure` |
442+
| header | Header in response that separated by spaces. `return code`,`{param type}`,`data type`,`comment` |
443+
| router | Path definition that separated by spaces. `path`,`[httpMethod]` |
444+
| deprecatedrouter | As same as router, but deprecated. |
445+
| x-name | The extension key, must be start by x- and take only json value. |
446+
| x-codeSample | Optional Markdown usage. take `file` as parameter. This will then search for a file named like the summary in the given folder. |
447+
| deprecated | Mark endpoint as deprecated. |
447448
448449
449450

‎README_zh-CN.md

+17-15
Original file line numberDiff line numberDiff line change
@@ -378,23 +378,25 @@ swag fmt -d ./ --exclude ./internal
378378

379379
Example [celler/controller](https://github.com/swaggo/swag/tree/master/example/celler/controller)
380380

381-
| 注释 | 描述 |
382-
| -------------------- | ------------------------------------------------------------------------------------------------------- |
383-
| description | 操作行为的详细说明。 |
384-
| description.markdown | 应用程序的简短描述。该描述将从名为`endpointname.md`的文件中读取。 |
385-
| id | 用于标识操作的唯一字符串。在所有API操作中必须唯一。 |
386-
| tags | 每个API操作的标签列表，以逗号分隔。 |
381+
| 注释 | 描述 |
382+
|----------------------|------------------------------------------------------------------------------------------------|
383+
| description | 操作行为的详细说明。 |
384+
| description.markdown | 应用程序的简短描述。该描述将从名为`endpointname.md`的文件中读取。 |
385+
| id | 用于标识操作的唯一字符串。在所有API操作中必须唯一。 |
386+
| tags | 每个API操作的标签列表，以逗号分隔。 |
387387
| summary | 该操作的简短摘要。 |
388-
| accept | API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“[Mime类型](#mime类型)”中所述。 |
389-
| produce | API可以生成的MIME类型的列表。值必须如“[Mime类型](#mime类型)”中所述。 |
388+
| accept | API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“[Mime类型](#mime类型)”中所述。 |
389+
| produce | API可以生成的MIME类型的列表。值必须如“[Mime类型](#mime类型)”中所述。 |
390390
| param | 用空格分隔的参数。`param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` |
391-
| security | 每个API操作的[安全性](#安全性)。 |
392-
| success | 以空格分隔的成功响应。`return code`,`{param type}`,`data type`,`comment` |
393-
| failure | 以空格分隔的故障响应。`return code`,`{param type}`,`data type`,`comment` |
394-
| response | 与success、failure作用相同 |
395-
| header | 以空格分隔的头字段。 `return code`,`{param type}`,`data type`,`comment` |
396-
| router | 以空格分隔的路径定义。 `path`,`[httpMethod]` |
397-
| x-name | 扩展字段必须以`x-`开头，并且只能使用json值。 |
391+
| security | 每个API操作的[安全性](#安全性)。 |
392+
| success | 以空格分隔的成功响应。`return code`,`{param type}`,`data type`,`comment` |
393+
| failure | 以空格分隔的故障响应。`return code`,`{param type}`,`data type`,`comment` |
394+
| response | 与success、failure作用相同 |
395+
| header | 以空格分隔的头字段。 `return code`,`{param type}`,`data type`,`comment` |
396+
| router | 以空格分隔的路径定义。 `path`,`[httpMethod]` |
397+
| deprecatedrouter | 与router相同，但是是deprecated的。 |
398+
| x-name | 扩展字段必须以`x-`开头，并且只能使用json值。 |
399+
| deprecated | 将当前API操作的所有路径设置为deprecated |
398400

399401
## Mime类型
400402

‎operation.go

+6-2
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import (
2121
type RouteProperties struct {
2222
HTTPMethod string
2323
Path string
24+
Deprecated bool
2425
}
2526

2627
// Operation describes a single API operation on a path.
@@ -147,7 +148,9 @@ func (operation *Operation) ParseComment(comment string, astFile *ast.File) erro
147148
case headerAttr:
148149
return operation.ParseResponseHeaderComment(lineRemainder, astFile)
149150
case routerAttr:
150-
return operation.ParseRouterComment(lineRemainder)
151+
return operation.ParseRouterComment(lineRemainder, false)
152+
case deprecatedRouterAttr:
153+
return operation.ParseRouterComment(lineRemainder, true)
151154
case securityAttr:
152155
return operation.ParseSecurityComment(lineRemainder)
153156
case deprecatedAttr:
@@ -707,7 +710,7 @@ func parseMimeTypeList(mimeTypeList string, typeList *[]string, format string) e
707710
var routerPattern = regexp.MustCompile(`^(/[\w./\-{}+:$]*)[[:blank:]]+\[(\w+)]`)
708711

709712
// ParseRouterComment parses comment for given `router` comment string.
710-
func (operation *Operation) ParseRouterComment(commentLine string) error {
713+
func (operation *Operation) ParseRouterComment(commentLine string, deprecated bool) error {
711714
matches := routerPattern.FindStringSubmatch(commentLine)
712715
if len(matches) != 3 {
713716
return fmt.Errorf("can not parse router comment \"%s\"", commentLine)
@@ -716,6 +719,7 @@ func (operation *Operation) ParseRouterComment(commentLine string) error {
716719
signature := RouteProperties{
717720
Path: matches[1],
718721
HTTPMethod: strings.ToUpper(matches[2]),
722+
Deprecated: deprecated,
719723
}
720724

721725
if _, ok := allMethod[signature.HTTPMethod]; !ok {

‎operation_test.go

+15
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ import (
55
"go/ast"
66
goparser "go/parser"
77
"go/token"
8+
"os"
9+
"path/filepath"
810
"testing"
911

1012
"github.com/go-openapi/spec"
@@ -2416,3 +2418,16 @@ func TestParseCodeSamples(t *testing.T) {
24162418
assert.Error(t, err, "no error should be thrown")
24172419
})
24182420
}
2421+
2422+
func TestParseDeprecatedRouter(t *testing.T) {
2423+
p := New()
2424+
searchDir := "./testdata/deprecated_router"
2425+
if err := p.ParseAPI(searchDir, mainAPIFile, defaultParseDepth); err != nil {
2426+
t.Error("Failed to parse api: " + err.Error())
2427+
}
2428+
2429+
b, _ := json.MarshalIndent(p.swagger, "", " ")
2430+
expected, err := os.ReadFile(filepath.Join(searchDir, "expected.json"))
2431+
assert.NoError(t, err)
2432+
assert.Equal(t, expected, b)
2433+
}

‎parser.go

+5
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ const (
4343
headerAttr = "@header"
4444
tagsAttr = "@tags"
4545
routerAttr = "@router"
46+
deprecatedRouterAttr = "@deprecatedrouter"
4647
summaryAttr = "@summary"
4748
deprecatedAttr = "@deprecated"
4849
securityAttr = "@security"
@@ -1081,6 +1082,10 @@ func processRouterOperation(parser *Parser, operation *Operation) error {
10811082
*op = &operation.Operation
10821083
}
10831084

1085+
if routeProperties.Deprecated {
1086+
(*op).Deprecated = routeProperties.Deprecated
1087+
}
1088+
10841089
parser.swagger.Paths.Paths[routeProperties.Path] = pathItem
10851090
}
10861091

‎testdata/deprecated_router/api/api.go

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
package api
2+
3+
import "net/http"
4+
5+
// @Description add Foo
6+
// @Deprecated
7+
// @Success 200 {string} string
8+
// @Router /testapi/foo1 [put]
9+
// @Router /testapi/foo1 [post]
10+
// @Router /test/api/foo1 [post]
11+
func AddFoo(w http.ResponseWriter, r *http.Request) {}
12+
13+
// @Description get Foo
14+
// @Success 200 {string} string
15+
// @Router /testapi/foo1 [get]
16+
// @DeprecatedRouter /test/api/foo1 [get]
17+
func GetFoo(w http.ResponseWriter, r *http.Request) {}

‎testdata/deprecated_router/expected.json

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
{
2+
"swagger": "2.0",
3+
"info": {
4+
"description": "test data for deprecated router",
5+
"title": "Swagger Example API",
6+
"termsOfService": "http://swagger.io/terms/",
7+
"contact": {},
8+
"version": "1.0"
9+
},
10+
"paths": {
11+
"/test/api/foo1": {
12+
"get": {
13+
"description": "get Foo",
14+
"deprecated": true,
15+
"responses": {
16+
"200": {
17+
"description": "OK",
18+
"schema": {
19+
"type": "string"
20+
}
21+
}
22+
}
23+
},
24+
"post": {
25+
"description": "add Foo",
26+
"deprecated": true,
27+
"responses": {
28+
"200": {
29+
"description": "OK",
30+
"schema": {
31+
"type": "string"
32+
}
33+
}
34+
}
35+
}
36+
},
37+
"/testapi/foo1": {
38+
"get": {
39+
"description": "get Foo",
40+
"responses": {
41+
"200": {
42+
"description": "OK",
43+
"schema": {
44+
"type": "string"
45+
}
46+
}
47+
}
48+
},
49+
"put": {
50+
"description": "add Foo",
51+
"deprecated": true,
52+
"responses": {
53+
"200": {
54+
"description": "OK",
55+
"schema": {
56+
"type": "string"
57+
}
58+
}
59+
}
60+
},
61+
"post": {
62+
"description": "add Foo",
63+
"deprecated": true,
64+
"responses": {
65+
"200": {
66+
"description": "OK",
67+
"schema": {
68+
"type": "string"
69+
}
70+
}
71+
}
72+
}
73+
}
74+
}
75+
}

‎testdata/deprecated_router/main.go

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
package main
2+
3+
// @title Swagger Example API
4+
// @version 1.0
5+
// @description test data for deprecated router
6+
// @termsOfService http://swagger.io/terms/
7+
8+
func main() {
9+
}

0 commit comments

Comments
 (0)
Please sign in to comment.