From a51a01cb50face381a531bf7e38a4b96a68c5e21 Mon Sep 17 00:00:00 2001 From: bughou Date: Sun, 12 Jul 2020 13:24:34 +0800 Subject: [PATCH] more unit test --- docs/group.go | 18 +++++++++++------- docs/route-req.go | 11 +++++++++++ docs/route-resp.go | 4 +++- docs/route.go | 1 + docs/z_test.go | 44 +++++++++++++++++++------------------------- 5 files changed, 45 insertions(+), 33 deletions(-) diff --git a/docs/group.go b/docs/group.go index 9b5fc93..232ec50 100644 --- a/docs/group.go +++ b/docs/group.go @@ -38,7 +38,7 @@ func (g *Group) Child(path, fullPath string, descs []string) Group { title += " (" + fullPath + ")" child.CreateReadme(title, descs[1:]) } - g.LinkInReadme(title, path) + g.LinkInReadme(title, path, false) } return child } @@ -63,7 +63,7 @@ func (g *Group) Route(method, path, fullPath string, handler interface{}) { log.Panic(err) } - g.LinkInReadme(route.Title(method, fullPath), path) + g.LinkInReadme(route.Title(method, fullPath), path, true) } func (g *Group) CreateReadme(title string, descs []string) { @@ -78,14 +78,18 @@ func (g *Group) CreateReadme(title string, descs []string) { } } -func (g *Group) LinkInReadme(title, href string) { +func (g *Group) LinkInReadme(title, href string, isRoute bool) { buf := bytes.NewBufferString("##") - if g.depth > 0 { - buf.WriteString(strings.Repeat("#", g.depth)) + depth := g.depth + if isRoute && depth == 0 { + depth = 1 + } + if depth > 0 { + buf.WriteString(strings.Repeat("#", depth)) } buf.WriteString(" ") - if g.depth > 0 { - buf.WriteString(strings.Repeat("　", g.depth)) // use a full-width space + if depth > 0 { + buf.WriteString(strings.Repeat("　", depth)) // use a full-width space } switch href { diff --git a/docs/route-req.go b/docs/route-req.go index 27ad74f..8c2e9b4 100644 --- a/docs/route-req.go +++ b/docs/route-req.go @@ -23,6 +23,15 @@ func (r *Route) Title(method, fullPath string) string { return title + " ： " + method + " " + html.EscapeString(fullPath) } +func (r *Route) Desc(buf *bytes.Buffer) { + if f, ok := r.req.FieldByName("Desc"); ok { + if desc := strings.TrimSpace(string(f.Tag)); desc != "" { + buf.WriteString(desc) + buf.WriteByte('\n') + } + } +} + func (r *Route) Param(buf *bytes.Buffer, fullPath string) { f, ok := r.req.FieldByName("Param") if !ok { @@ -75,6 +84,7 @@ func (r *Route) Body(buf *bytes.Buffer) { } buf.WriteString("\n## 请求体说明（application/json）\n") + buf.WriteString("```json5\n") if b, err := jsondoc.MarshalIndent( reflect.Zero(f.Type).Interface(), false, "", " ", ); err != nil { @@ -82,4 +92,5 @@ func (r *Route) Body(buf *bytes.Buffer) { } else { buf.Write(b) } + buf.WriteString("\n```\n") } diff --git a/docs/route-resp.go b/docs/route-resp.go index 0eaf778..0d656b7 100644 --- a/docs/route-resp.go +++ b/docs/route-resp.go @@ -29,12 +29,13 @@ func (r *Route) ResHeader(buf *bytes.Buffer) { } func (r *Route) ResBody(buf *bytes.Buffer) { - f, ok := r.resp.FieldByName("Body") + f, ok := r.resp.FieldByName("Data") if !ok { return } buf.WriteString("\n## 返回体说明（application/json）\n") + buf.WriteString("```json5\n") if b, err := jsondoc.MarshalIndent( resBody{Data: reflect.Zero(f.Type).Interface()}, false, "", " ", ); err != nil { @@ -42,6 +43,7 @@ func (r *Route) ResBody(buf *bytes.Buffer) { } else { buf.Write(b) } + buf.WriteString("\n```\n") } type resBody struct { diff --git a/docs/route.go b/docs/route.go index f801e1c..1aad899 100644 --- a/docs/route.go +++ b/docs/route.go @@ -24,6 +24,7 @@ func (r *Route) Parse(handler interface{}) bool { func (r *Route) Doc(method, fullPath string) []byte { buf := bytes.NewBufferString("# " + r.Title(method, fullPath) + "\n") + r.Desc(buf) r.Param(buf, fullPath) r.Query(buf) diff --git a/docs/z_test.go b/docs/z_test.go index dd21755..d13e9ed 100644 --- a/docs/z_test.go +++ b/docs/z_test.go @@ -14,7 +14,7 @@ func ExampleGroup() { accounts := router.Group("/", "账号", "用户、公司、员工、角色、权限") accounts.Group("/users", "用户"). Get(`/`, testHandler). - Get(`/(?P\w+)/(?P\d+)`, testHandler) + Get(`/(?P\w+)/(?P\d+)`, testHandler2) accounts.Group("/companies", "公司") @@ -26,52 +26,46 @@ func ExampleGroup() { } type T struct { - Type string - Id int - Flag bool + Type string `c:"类型"` + Id int `c:"ID"` + Flag bool `c:"标志"` } func testHandler(req struct { Title string `用户列表` + Desc string `列出所有的用户` Query struct { - Page int + Page int `c:"页码"` T } Header struct { - Cookie string + Cookie string `c:"Cookie中包含会话信息"` } Body struct { - Name string + Name string `c:"名称"` T } }, resp *struct { - Error error - Data interface{} - Header struct { - SetCookie string `header:"Set-Cookie"` + Error error + Data []struct { + Id int `c:"ID"` + Name string `c:"名称"` } }) { } func testHandler2(req struct { Title string `用户详情` + Desc string `获取用户的详细信息` Param T - Query struct { - Page int - T - } - Header struct { - Cookie string - } - Body struct { - Name string - T - } }, resp *struct { - Error error - Data interface{} + Error error + Data struct { + Id int `c:"ID"` + Name string `c:"名称"` + } Header struct { - SetCookie string `header:"Set-Cookie"` + SetCookie string `header:"Set-Cookie" c:"返回登录会话"` } }) { }