feat: add generation of type description to schema (swaggo#708)

README.md

@@ -613,13 +613,52 @@ type Account struct {
 ### Description of struct
 
 ```go
+// Account model info
+// @Description User account information
+// @Description with user id and username
 type Account struct {
 	// ID this is userid
 	ID   int    `json:"id"`
 	Name string `json:"name"` // This is Name
 }
 ```
 
+generated swagger doc as follows:
+```json
+"Account": {
+  "type":"object",
+  "description": "User account information with user id and username"
+  "properties": {
+    "id": {
+      "type": "integer",
+      "description": "ID this is userid"
+    },
+    "name": {
+      "type":"string",
+      "description": "This is Name"
+    }
+  }
+}
+```
+
+generated swagger doc as follows:
+```json
+"Account": {
+  "type":"object",
+  "description": "User account information"
+  "properties": {
+    "id": {
+      "type": "integer",
+      "description": "ID this is userid"
+    },
+    "name": {
+      "type":"string",
+      "description": "This is Name"
+    }
+  }
+}
+```
+
 ### Use swaggertype tag to supported custom type
 [#201](https://github.com/swaggo/swag/issues/201#issuecomment-475479409)
 

parser.go

@@ -954,6 +954,11 @@ func (parser *Parser) ParseDefinition(typeSpecDef *TypeSpecDef) (*Schema, error)
 		return nil, err
 	}
 
+	err = fillDefinition(definition, typeSpecDef.File, typeSpecDef)
+	if err != nil {
+		return nil, err
+	}
+
 	s := Schema{
 		Name:    refTypeName,
 		PkgPath: typeSpecDef.PkgPath,
@@ -978,6 +983,60 @@ func fullTypeName(pkgName, typeName string) string {
 	return typeName
 }
 
+// fillDefinition additionally fills fields in definition (spec.Schema)
+// TODO: If .go file contains many types, it may work for a long time
+func fillDefinition(definition *spec.Schema, file *ast.File, typeSpecDef *TypeSpecDef) error {
+	if definition.Description == "" {
+		for _, astDeclaration := range file.Decls {
+			generalDeclaration, ok := astDeclaration.(*ast.GenDecl)
+			if !ok || generalDeclaration.Tok != token.TYPE {
+				continue
+			}
+
+			for _, astSpec := range generalDeclaration.Specs {
+				typeSpec, ok := astSpec.(*ast.TypeSpec)
+				if !ok || typeSpec != typeSpecDef.TypeSpec {
+					continue
+				}
+
+				definition.Description =
+					extractDeclarationDescription(typeSpec.Doc, typeSpec.Comment, generalDeclaration.Doc)
+				return nil
+			}
+		}
+	}
+
+	return nil
+}
+
+// extractDeclarationDescription gets first description
+// from attribute descriptionAttr in commentGroups (ast.CommentGroup)
+func extractDeclarationDescription(commentGroups ...*ast.CommentGroup) (description string) {
+	for _, commentGroup := range commentGroups {
+		if commentGroup == nil {
+			continue
+		}
+
+		isHandlingDescription := false
+		for _, comment := range commentGroup.List {
+			commentText := strings.TrimSpace(strings.TrimLeft(comment.Text, "/"))
+			attribute := strings.Split(commentText, " ")[0]
+			if strings.ToLower(attribute) != descriptionAttr && !isHandlingDescription {
+				continue
+			}
+
+			if strings.ToLower(attribute) != descriptionAttr && isHandlingDescription {
+				break
+			}
+
+			isHandlingDescription = true
+			description += " " + strings.TrimSpace(commentText[len(attribute):])
+		}
+	}
+
+	return strings.TrimLeft(description, " ")
+}
+
 // parseTypeExpr parses given type expression that corresponds to the type under
 // given name and package, and returns swagger schema for it.
 func (parser *Parser) parseTypeExpr(file *ast.File, typeExpr ast.Expr, ref bool) (*spec.Schema, error) {