From a06a54bb355899312ea39036ac90c6f988b3c34e Mon Sep 17 00:00:00 2001 From: caixw Date: Wed, 4 Dec 2024 14:04:18 +0800 Subject: [PATCH] =?UTF-8?q?feat(openapi):=20New=20=E5=9C=A8=E5=88=9D?= =?UTF-8?q?=E5=A7=8B=E5=8C=96=E4=B9=8B=E5=90=8E=E5=8D=B3=E6=B7=BB=E5=8A=A0?= =?UTF-8?q?=E4=BA=86=20EmptyResponseRef=20=E7=A9=BA=E7=9A=84=E8=BF=94?= =?UTF-8?q?=E5=9B=9E=E5=AF=B9=E8=B1=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- locales/und.yaml | 3 +++ locales/zh.yaml | 3 +++ openapi/middleware.go | 10 ++++++++++ openapi/openapi.go | 7 +++++++ openapi/option.go | 11 ----------- openapi/option_test.go | 5 +++-- server/config/CONFIG.html | 3 +++ 7 files changed, 29 insertions(+), 13 deletions(-) diff --git a/locales/und.yaml b/locales/und.yaml index aaf61bec..fcf2241a 100755 --- a/locales/und.yaml +++ b/locales/und.yaml @@ -43,6 +43,9 @@ messages: - key: no available peer message: msg: no available peer + - key: no response + message: + msg: no response - key: not found message: msg: not found diff --git a/locales/zh.yaml b/locales/zh.yaml index 116de5e8..e3bc6cfa 100644 --- a/locales/zh.yaml +++ b/locales/zh.yaml @@ -45,6 +45,9 @@ messages: - key: no available peer message: msg: 没有有效的节点 + - key: no response + message: + msg: 无返回内容 - key: not found message: msg: 未找到 diff --git a/openapi/middleware.go b/openapi/middleware.go index d744f383..1923ddaf 100644 --- a/openapi/middleware.go +++ b/openapi/middleware.go @@ -305,6 +305,16 @@ func (o *Operation) ResponseRef(status, ref string, summary, description web.Loc return o } +// Response200 相当于 o.Response("200", resp, nil, nil) +func (o *Operation) Response200(resp any) *Operation { + return o.Response("200", resp, nil, nil) +} + +// ResponseEmpty 相当于 o.ResponseRef(status, EmptyResponseRef, nil, nil) +func (o *Operation) ResponseEmpty(status string) *Operation { + return o.ResponseRef(status, EmptyResponseRef, nil, nil) +} + // CallbackRef 引用 components 中定义的回调对象 func (o *Operation) CallbackRef(name, ref string, summary, description web.LocaleStringer) *Operation { if _, found := o.d.components.callbacks[ref]; !found { diff --git a/openapi/openapi.go b/openapi/openapi.go index 123c7ba5..f80b7939 100644 --- a/openapi/openapi.go +++ b/openapi/openapi.go @@ -90,6 +90,9 @@ const ( SecuritySchemeTypeOpenIDConnect = "openIdConnect" ) +// 文档中表示没有返回对象在 components/responses 中的引用值 +const EmptyResponseRef = "empty-response-ref" + type ( // Document openapi 文档 Document struct { @@ -431,6 +434,10 @@ func New(s web.Server, title web.LocaleStringer, o ...Option) *Document { s: s, } + o = append(o, WithResponse(&Response{ + Ref: &Ref{Ref: EmptyResponseRef}, + Description: web.Phrase("no response"), + })) for _, opt := range o { opt(doc) } diff --git a/openapi/option.go b/openapi/option.go index 9cf0154c..6dd35cfc 100644 --- a/openapi/option.go +++ b/openapi/option.go @@ -87,17 +87,6 @@ func WithProblemResponse() Option { }, "4XX", "5XX") } -// WithClassicResponse 提供框架一些常用的 [Response] 对象 -// -// 包含了 4XX 和 5XX 的错误对象； -// 包含了一个 ref 为 empty 的空对象； -func WithClassicResponse() Option { - return WithOptions( - WithProblemResponse(), - WithResponse(&Response{Ref: &Ref{Ref: "empty"}}), - ) -} - // WithMediaType 指定所有接口可用的媒体类型 // // t 用于指定支持的媒体类型，必须是 [web.Server] 实例支持的类型。 diff --git a/openapi/option_test.go b/openapi/option_test.go index 5b4b035e..2415a924 100644 --- a/openapi/option_test.go +++ b/openapi/option_test.go @@ -64,7 +64,8 @@ func TestWithResponse(t *testing.T) { WithResponse(&Response{Ref: &Ref{Ref: "500"}}, "500"), ) a.NotNil(d). - Length(d.components.responses, 2). + Length(d.components.responses, 3). + Length(d.responses, 2). Equal(d.responses["400"], "400"). Equal(d.responses["500"], "500") } @@ -76,7 +77,7 @@ func TestWithProblemResponse(t *testing.T) { d := New(ss, web.Phrase("desc"), WithProblemResponse()) a.NotNil(d). Length(d.responses, 2). - Length(d.components.responses, 1). + Length(d.components.responses, 2). Equal(d.responses["4XX"], "problem"). Equal(d.responses["5XX"], "problem") } diff --git a/server/config/CONFIG.html b/server/config/CONFIG.html index a9efc7a2..3613075c 100644 --- a/server/config/CONFIG.html +++ b/server/config/CONFIG.html @@ -160,6 +160,9 @@

httpConfig

port,omitemptyport,omitemptyport,attr,omitemptystring

端口

格式与 [http.Server.Addr] 相同。可以为空，表示由 [http.Server] 确定其默认值。 +url,omitemptyurl,omitemptyurl,omitemptystring

[web.Router.URL] 的默认前缀 +

如果是非标准端口，应该带上端口号。 +

NOTE: 每个路由可使用 [web.WithURLDomain] 重新定义该值。 requestID,omitemptyrequestID,omitemptyrequestID,omitemptystring

x-request-id 的报头名称

如果为空，则采用 [header.XRequestID] 作为默认值。 certificates,omitemptycertificates,omitemptycertificates>certificate,omitemptycertificateConfig

网站的域名证书