refactor(openapi): MarkdownProblems 可以自定义标题的级别

openapi/openapi_test.go

@@ -12,6 +12,7 @@ import (
 	"golang.org/x/text/language"
 
 	"github.com/issue9/web"
+	"github.com/issue9/web/locales"
 	"github.com/issue9/web/server"
 )
 
@@ -21,6 +22,7 @@ func newServer(a *assert.Assertion) web.Server {
 	})
 	a.NotError(err).NotNil(s)
 
+	s.Locale().LoadMessages("*.yaml", locales.Locales...)
 	a.NotError(s.Locale().SetString(language.SimplifiedChinese, "lang", "简体"))
 	a.NotError(s.Locale().SetString(language.TraditionalChinese, "lang", "繁体"))
 

openapi/option.go

@@ -13,13 +13,22 @@ import (
 
 type Option func(*Document)
 
-// WithHead 是否生成 HEAD 接口请求
-func WithHead(enable bool) Option {
+// WithOptions 合并多个 [Option] 为一个
+func WithOptions(o ...Option) Option {
+	return func(d *Document) {
+		for _, opt := range o {
+			opt(d)
+		}
+	}
+}
+
+// WithHeadMethod 是否生成 HEAD 接口请求
+func WithHeadMethod(enable bool) Option {
 	return func(d *Document) { d.enableHead = enable }
 }
 
-// WithOptions 是否生成 OPTIONS 请求
-func WithOptions(enable bool) Option {
+// WithOptionsMethod 是否生成 OPTIONS 请求
+func WithOptionsMethod(enable bool) Option {
 	return func(d *Document) { d.enableOptions = enable }
 }
 
@@ -76,6 +85,17 @@ 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

@@ -14,6 +14,15 @@ import (
 	"github.com/issue9/web/mimetype/json"
 )
 
+func TestWithOptions(t *testing.T) {
+	a := assert.New(t, false)
+
+	ss := newServer(a)
+	d := New(ss, web.Phrase("title"), WithOptions(WithHeadMethod(true), WithOptionsMethod(true)))
+	a.True(d.enableHead).
+		True(d.enableOptions)
+}
+
 func TestWithHTML(t *testing.T) {
 	a := assert.New(t, false)
 

openapi/utils.go

@@ -95,15 +95,18 @@ func getPathParams(path string) []string {
 }
 
 // MarkdownProblems 将 problems 的内容生成为 markdown
-func MarkdownProblems(s web.Server) web.LocaleStringer {
+//
+// titleLevlel 标题的级别，1-6；
+func MarkdownProblems(s web.Server, titleLevlel int) web.LocaleStringer {
 	buf := &errwrap.Buffer{}
 
+	ss := strings.Repeat("#", titleLevlel)
 	args := make([]any, 0, 30)
 	s.Problems().Visit(func(status int, lp *web.LocaleProblem) {
-		buf.WString("## %s \n\n").
+		buf.Printf("%s %s ", ss, lp.Type()).
 			WString("%s\n\n").
 			WString("%s\n\n")
-		args = append(args, lp.Type(), lp.Title, lp.Detail)
+		args = append(args, lp.Title, lp.Detail)
 	})
 
 	return web.Phrase(buf.String(), args...)

openapi/utils_test.go

@@ -5,6 +5,7 @@
 package openapi
 
 import (
+	"strings"
 	"testing"
 
 	"github.com/issue9/assert/v4"
@@ -47,3 +48,21 @@ func TestGetPathParams(t *testing.T) {
 	a.Equal(getPathParams("/path/{id}/{id2}"), []string{"id", "id2"})
 	a.Equal(getPathParams("/path/{id:number}/{id2}"), []string{"id:number", "id2"})
 }
+
+func TestMarkdownProblems(t *testing.T) {
+	a := assert.New(t, false)
+	ss := newServer(a)
+	p := ss.Locale().NewPrinter(language.SimplifiedChinese)
+
+	txt := MarkdownProblems(ss, 2)
+	lines := strings.Split(txt.LocaleString(p), "\n\n")
+	a.Equal(lines[0], "## 400 Bad Request").
+		Equal(lines[1], "表示客户端错误，比如，错误的请求语法、无效的请求消息帧或欺骗性的请求路由等，服务器无法或不会处理该请求。").
+		Equal(lines[2], "## 401 Unauthorized")
+
+	txt = MarkdownProblems(ss, 3)
+	lines = strings.Split(txt.LocaleString(p), "\n\n")
+	a.Equal(lines[0], "### 400 Bad Request").
+		Equal(lines[1], "表示客户端错误，比如，错误的请求语法、无效的请求消息帧或欺骗性的请求路由等，服务器无法或不会处理该请求。").
+		Equal(lines[2], "### 401 Unauthorized")
+}