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 @@
端口
格式与 [http.Server.Addr] 相同。可以为空,表示由 [http.Server] 确定其默认值。 +
[web.Router.URL] 的默认前缀 +
如果是非标准端口,应该带上端口号。 +
NOTE: 每个路由可使用 [web.WithURLDomain] 重新定义该值。
x-request-id 的报头名称
如果为空,则采用 [header.XRequestID] 作为默认值。
网站的域名证书