docs(cmd/web): 更新文档

issue9 · May 31, 2024 · 1f01461 · 1f01461
1 parent 311cc5c
commit 1f01461
Show file tree

Hide file tree

Showing 2 changed files with 5 additions and 5 deletions.
diff --git a/cmd/web/locales/zh-CN.yaml b/cmd/web/locales/zh-CN.yaml
@@ -250,7 +250,7 @@ messages:
               @tag tag1 tag2 该接口要关联的标签，多个标签用空格分隔；
               @header key desc 指定请求报头；
               @cookie key desc 指定了 cookie；
-              @path key type desc 指定了路径中的参数，key 为参数名，type 为参数类型，只能是基本类型；
+              @path key type desc 指定了路径中的参数，key 为参数名，type 为参数类型，只能是基本类型，相同路径下的不同请求方法可以只定义一次；
               @query object.path desc 查询参数，object.path 表示指向查询参数的定义，可参考 schema 节的说明；
               @req media object.path desc 定义请求格式，media 如果采用全局指定的默认值，可以用 *，如果是多个值，用逗号分隔；
               @resp status media object.path desc 指定返回的数据类型；

diff --git a/cmd/web/restdoc/openapi/path.go b/cmd/web/restdoc/openapi/path.go
@@ -36,18 +36,18 @@ func (doc *OpenAPI) addAPI(path, method string, o *openapi3.Operation) {
 
 	doc.doc.AddOperation(path, method, o)
 
-	if index := slices.IndexFunc(o.Parameters, isPathParams); index < 0 {
+	if index := slices.IndexFunc(o.Parameters, isPathParams); index < 0 { // 没有参数
 		return
 	}
 
-	p := doc.doc.Paths.Find(path)
-	if index := slices.IndexFunc(p.Parameters, isPathParams); index >= 0 {
+	pathItem := doc.doc.Paths.Find(path)
+	if index := slices.IndexFunc(pathItem.Parameters, isPathParams); index >= 0 { // 已由其它 Operation 添加了参数
 		return
 	}
 
 	for _, param := range o.Parameters {
 		if param.Value.In == openapi3.ParameterInPath {
-			p.Parameters = append(p.Parameters, param)
+			pathItem.Parameters = append(pathItem.Parameters, param)
 		}
 	}
 	o.Parameters = slices.DeleteFunc(o.Parameters, isPathParams)