Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: disable map tag summary and description from the OpenAPI Operation to PathItem #2823

Merged
merged 3 commits into from Aug 2, 2023

Conversation

WankkoRee
Copy link
Contributor

因为当前 tag 都是针对 Operation 对象设置的,不应该将 Operation 的 summary 和 description 直接添加到 PathItem 。

如存在POST /user的 summary 为新增用户,存在DELETE /user的 summary 为删除用户,两者为相反操作,其 PathItem 的 summary 应当留空而不是使用其中一个。

实际测试:

package main

import (
	"context"
	"fmt"

	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/ghttp"
)

type HelloReq struct {
	g.Meta `path:"/hello" method:"get" sm:"sm" dc:"dc"`
	Name   string `v:"required" dc:"Your name"`
}
type HelloRes struct {
	Reply string `dc:"Reply content"`
}

type Hello struct{}

func (Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) {
	g.Log().Debugf(ctx, `receive say: %+v`, req)
	res = &HelloRes{
		Reply: fmt.Sprintf(`Hi %s`, req.Name),
	}
	return
}

func main() {
	s := g.Server()
	s.Use(ghttp.MiddlewareHandlerResponse)
	s.Group("/", func(group *ghttp.RouterGroup) {
		group.Bind(
			new(Hello),
		)
	})
	s.Run()
}
{
    "openapi": "3.0.0",
    "components": {
        "schemas": {
            "main.HelloReq": {
                "description": "dc",
                "properties": {
                    "Name": {
                        "description": "Your name",
                        "format": "string",
                        "properties": {},
                        "type": "string"
                    }
                },
                "required": [
                    "Name"
                ],
                "type": "object"
            },
            "main.HelloRes": {
                "properties": {
                    "Reply": {
                        "description": "Reply content",
                        "format": "string",
                        "properties": {},
                        "type": "string"
                    }
                },
                "type": "object"
            }
        }
    },
    "info": {
        "title": "",
        "version": ""
    },
    "paths": {
        "/hello": {
-           "description": "dc",
            "get": {
                "description": "dc",
                "parameters": [
                    {
                        "description": "Your name",
                        "in": "query",
                        "name": "Name",
                        "required": true,
                        "schema": {
                            "description": "Your name",
                            "format": "string",
                            "properties": {},
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/main.HelloRes"
                                }
                            }
                        },
                        "description": ""
                    }
                },
                "summary": "sm"
+           }
-           },
-           "summary": "sm"
        }
    }
}

各家支持解析 OpenAPI 的工具对于 PathItem 中的 summary 和 description 并不友好,所以理论上不太存在需要自定义这两个字段的需求。

如 Apifox 会把 summary 当成一个方法:

a31f5de0d3a28d3488b27bb8b0881c4

@houseme houseme requested a review from gqcn August 1, 2023 08:22
@gqcn
Copy link
Member

gqcn commented Aug 1, 2023

@WankkoRee 感谢您的贡献,我需要花点时间仔细看看哈。

@Issues-translate-bot
Copy link

Bot detected the issue body's language is not English, translate it automatically. 👯👭🏻🧑‍🤝‍🧑👫🧑🏿‍🤝‍🧑🏻👩🏾‍🤝‍👨🏿👬🏿


@WankkoRee Thanks for your contribution, I need to take a moment to take a closer look ha.

net/goai/goai_path.go Show resolved Hide resolved
@gqcn
Copy link
Member

gqcn commented Aug 1, 2023

@WankkoRee CI失败了请看看呢,另外请增加该修改对应的单测哈。

@Issues-translate-bot
Copy link

Bot detected the issue body's language is not English, translate it automatically. 👯👭🏻🧑‍🤝‍🧑👫🧑🏿‍🤝‍🧑🏻👩🏾‍🤝‍👨🏿👬🏿


@WankkoRee CI failed, please take a look, and please add the single test corresponding to this modification.

@codecov-commenter
Copy link

codecov-commenter commented Aug 2, 2023

Codecov Report

Patch coverage: 91.66% and project coverage change: +0.06% 🎉

Comparison is base (e0e0043) 79.22% compared to head (3f007b1) 79.29%.
Report is 4 commits behind head on master.

❗ Your organization is not using the GitHub App Integration. As a result you may experience degraded service beginning May 15th. Please install the Github App Integration for your organization. Read more.

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #2823      +/-   ##
==========================================
+ Coverage   79.22%   79.29%   +0.06%     
==========================================
  Files         633      626       -7     
  Lines       52242    51952     -290     
==========================================
- Hits        41391    41194     -197     
+ Misses       8808     8734      -74     
+ Partials     2043     2024      -19     
Flag Coverage Δ
go-1.15-386 ?
go-1.15-amd64 ?
go-1.16-386 ?
go-1.16-amd64 ?
go-1.17-386 ?
go-1.17-amd64 ?
go-1.18-386 ?
go-1.18-amd64 79.28% <91.66%> (+0.45%) ⬆️
go-1.19-386 ?
go-1.19-amd64 ?
go-1.20-386 ?
go-1.20-amd64 79.23% <91.66%> (+0.02%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed Coverage Δ
net/goai/goai_path.go 74.13% <91.66%> (+1.01%) ⬆️

... and 21 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@WankkoRee
Copy link
Contributor Author

单测已修复。

@Issues-translate-bot
Copy link

Bot detected the issue body's language is not English, translate it automatically. 👯👭🏻🧑‍🤝‍🧑👫🧑🏿‍🤝‍🧑🏻👩🏾‍🤝‍👨🏿👬🏿


Single test has been fixed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants