feat(openapi): New 在初始化之后即添加了 EmptyResponseRef 空的返回对象

Author: caixw

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

locales/zh.yaml

@@ -45,6 +45,9 @@ messages:
     - key: no available peer
       message:
         msg: 没有有效的节点
+    - key: no response
+      message:
+        msg: 无返回内容
     - key: not found
       message:
         msg: 未找到

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 {

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)
 	}

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] 实例支持的类型。

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")
 }

server/config/CONFIG.html

@@ -160,6 +160,9 @@ <h2 id="httpConfig">httpConfig</h2>
 					<tbody>
 					<tr><td>port,omitempty</td><td>port,omitempty</td><td>port,attr,omitempty</td><td>string</td><td><p>端口
 <p>格式与 [http.Server.Addr] 相同。可以为空，表示由 [http.Server] 确定其默认值。
+</td></tr><tr><td>url,omitempty</td><td>url,omitempty</td><td>url,omitempty</td><td>string</td><td><p>[web.Router.URL] 的默认前缀
+<p>如果是非标准端口，应该带上端口号。
+<p>NOTE: 每个路由可使用 [web.WithURLDomain] 重新定义该值。
 </td></tr><tr><td>requestID,omitempty</td><td>requestID,omitempty</td><td>requestID,omitempty</td><td>string</td><td><p>x-request-id 的报头名称
 <p>如果为空，则采用 [header.XRequestID] 作为默认值。
 </td></tr><tr><td>certificates,omitempty</td><td>certificates,omitempty</td><td>certificates&gt;certificate,omitempty</td><td><a href="#certificateConfig">certificateConfig</a></td><td><p>网站的域名证书