From f869aa1bb0958e19fdeed0a2c5534fb0cb408cc7 Mon Sep 17 00:00:00 2001
From: caixw <xnotepad@gmail.com>
Date: Mon, 2 Dec 2024 10:31:10 +0800
Subject: [PATCH] =?UTF-8?q?refactor(oepnapi):=20Schema=20=E5=8F=AF?=
 =?UTF-8?q?=E4=BB=A5=E4=B8=BA=20nil=20=E6=B7=BB=E5=8A=A0=E4=BA=86=20Markdo?=
 =?UTF-8?q?wnProblems?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 cmd/web/go.mod    |  2 +-
 openapi/option.go |  5 +++--
 openapi/schema.go | 12 ++++++++----
 openapi/utils.go  | 16 ++++++++++++++++
 4 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/cmd/web/go.mod b/cmd/web/go.mod
index a6c71af9..a91c1cb8 100644
--- a/cmd/web/go.mod
+++ b/cmd/web/go.mod
@@ -10,7 +10,7 @@ require (
 	github.com/issue9/logs/v7 v7.6.4
 	github.com/issue9/source v0.11.6
 	github.com/issue9/term/v3 v3.3.2
-	github.com/issue9/web v0.98.0
+	github.com/issue9/web v0.99.3
 	golang.org/x/text v0.20.0
 	gopkg.in/yaml.v3 v3.0.1
 )
diff --git a/openapi/option.go b/openapi/option.go
index 5e784ac0..f6683110 100644
--- a/openapi/option.go
+++ b/openapi/option.go
@@ -49,7 +49,8 @@ func WithHTML(tpl, assets, logo string) Option {
 // 一般用于指定非正常状态的返回对象，比如 400 状态码的对象。
 //
 // resp 返回对象，需要指定 resp.Ref.Ref，其它接口可以通过 Ref 引用该对象；
-// status: 状态码，可以是 4XX 的形式，如果该值不为空，那么将当前对象以此状态码应用到所有的接口；
+// status: 状态码，可以是 4XX 的形式，如果该值不为空，那么将当前对象以此状态码应用到所有的接口，
+// 否则仅仅是写入 components/responses，后续需要用户手动引用；
 //
 // NOTE: 多次调用会依次添加
 func WithResponse(resp *Response, status ...string) Option {
@@ -311,7 +312,7 @@ func WithTag(name string, desc web.LocaleStringer, extDocURL string, extDocDesc
 // WithSecurityScheme 指定验证方案
 //
 // s 需要添加的验证方案；
-// scope 如果指定了该值，那么会以 s.ID 为名称，scope 为值添加至 openapi.securiy，
+// scope 如果指定了该值，那么会以 s.ID 为名称，scope 为值添加至 openapi.security，
 // scope 如果是多个参数，每个参数应该都是不同的；
 //
 // NOTE: 多次调用会依次添加
diff --git a/openapi/schema.go b/openapi/schema.go
index 54d28a9d..85e41a69 100644
--- a/openapi/schema.go
+++ b/openapi/schema.go
@@ -105,9 +105,9 @@ func AllOfSchema(title, desc web.LocaleStringer, v ...any) *Schema {
 	return xOfSchema(2, title, desc, v...)
 }
 
-// - 0 anyof
-// - 1 oneof
-// - 2 allof
+// - 0 AnyOf
+// - 1 OneOf
+// - 2 AllOf
 func xOfSchema(typ int, title, desc web.LocaleStringer, v ...any) *Schema {
 	if len(v) == 0 {
 		panic("参数 v 必不可少")
@@ -138,6 +138,10 @@ func xOfSchema(typ int, title, desc web.LocaleStringer, v ...any) *Schema {
 }
 
 func newSchema(d *Document, v any, title, desc web.LocaleStringer) *Schema {
+	if v == nil {
+		return nil
+	}
+
 	s := &Schema{
 		Title:       title,
 		Description: desc,
@@ -147,8 +151,8 @@ func newSchema(d *Document, v any, title, desc web.LocaleStringer) *Schema {
 	if !rv.IsZero() {
 		s.Default = v
 	}
-
 	schemaFromType(d, rv.Type(), true, "", s)
+
 	return s
 }
 
diff --git a/openapi/utils.go b/openapi/utils.go
index 726b26ca..7a016ae1 100644
--- a/openapi/utils.go
+++ b/openapi/utils.go
@@ -11,6 +11,7 @@ import (
 	"slices"
 	"strings"
 
+	"github.com/issue9/errwrap"
 	orderedmap "github.com/wk8/go-ordered-map/v2"
 	"golang.org/x/text/message"
 
@@ -92,3 +93,18 @@ func getPathParams(path string) []string {
 
 	return ret
 }
+
+// MarkdownProblems 将 problems 的内容生成为 markdown
+func MarkdownProblems(s web.Server) web.LocaleStringer {
+	buf := &errwrap.Buffer{}
+
+	args := make([]any, 0, 30)
+	s.Problems().Visit(func(status int, lp *web.LocaleProblem) {
+		buf.WString("## %s \n\n").
+			WString("%s\n\n").
+			WString("%s\n\n")
+		args = append(args, lp.Type(), lp.Title, lp.Detail)
+	})
+
+	return web.Phrase(buf.String(), args...)
+}