more unit test

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 {

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,11 +84,13 @@ 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 {
 		log.Panic(err)
 	} else {
 		buf.Write(b)
 	}
+	buf.WriteString("\n```\n")
 }

docs/route-resp.go

@@ -29,19 +29,21 @@ 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 {
 		log.Panic(err)
 	} else {
 		buf.Write(b)
 	}
+	buf.WriteString("\n```\n")
 }
 
 type resBody struct {

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)

docs/z_test.go

@@ -14,7 +14,7 @@ func ExampleGroup() {
 	accounts := router.Group("/", "账号", "用户、公司、员工、角色、权限")
 	accounts.Group("/users", "用户").
 		Get(`/`, testHandler).
-		Get(`/(?P<type>\w+)/(?P<id>\d+)`, testHandler)
+		Get(`/(?P<type>\w+)/(?P<id>\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:"返回登录会话"`
 	}
 }) {
 }