From 1b25d8ef40dbb8a3608b51adf99a6684a35eeb99 Mon Sep 17 00:00:00 2001
From: "antoine.leveugle" <antoine.leveugle@gmail.com>
Date: Thu, 3 Sep 2020 16:06:15 +0200
Subject: [PATCH] feat: allow to add description on struct fields using tag
 openapi-description

---
 docparser/datatest/user.go |  1 +
 docparser/model.go         |  3 +++
 docparser/parser.go        | 12 ++++++++----
 docparser/parser_test.go   | 15 +++++++++++++++
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/docparser/datatest/user.go b/docparser/datatest/user.go
index b24ea89..796b198 100644
--- a/docparser/datatest/user.go
+++ b/docparser/datatest/user.go
@@ -109,6 +109,7 @@ type Pet struct {
 	JSONData            json.RawMessage           `json:"json_data"`
 	CustomString        otherpackage.CustomString `json:"custom_string"`
 	Test                Test                      `json:"test"`
+	FieldWithDecription string                    `json:"with-description" openapi-description:"my description"`
 }
 
 // Dog struct
diff --git a/docparser/model.go b/docparser/model.go
index 80ff24f..b5d2021 100644
--- a/docparser/model.go
+++ b/docparser/model.go
@@ -145,6 +145,7 @@ type schema struct {
 	Properties           map[string]*schema     `yaml:",omitempty"`
 	AdditionalProperties *schema                `yaml:"additionalProperties,omitempty"`
 	OneOf                []schema               `yaml:"oneOf,omitempty"`
+	Description          string                 `yaml:"description,omitempty"`
 }
 
 func (s *schema) RealName() string {
@@ -450,6 +451,8 @@ func (spec *openAPI) parseStructs(f *ast.File, tpe *ast.StructType) interface{}
 				p.Enum = j.enum
 			}
 
+			p.Description = j.description
+
 			if p != nil {
 				e.Properties[j.name] = p
 			}
diff --git a/docparser/parser.go b/docparser/parser.go
index 50c6390..0467a42 100644
--- a/docparser/parser.go
+++ b/docparser/parser.go
@@ -12,6 +12,8 @@ import (
 	"strings"
 )
 
+const jsonTagOpenAPIDescription = "openapi-description"
+
 var enumRegex = regexp.MustCompile(`enum=([\w ]+)`)
 var oneOfRegex = regexp.MustCompile(`oneof=([\w ]+)`) // validator.v9 enum tag is oneof
 
@@ -26,10 +28,11 @@ func parseFile(path string) (*ast.File, error) {
 }
 
 type jsonTagInfo struct {
-	name     string
-	ignore   bool
-	required bool
-	enum     []string
+	name        string
+	ignore      bool
+	required    bool
+	enum        []string
+	description string
 }
 
 func parseJSONTag(field *ast.Field) (j jsonTagInfo, err error) {
@@ -70,6 +73,7 @@ func parseJSONTag(field *ast.Field) (j jsonTagInfo, err error) {
 				j.name = jsonName
 				j.required = required
 				j.ignore = false
+				j.description = st.Get(jsonTagOpenAPIDescription)
 
 				return j, nil
 			}
diff --git a/docparser/parser_test.go b/docparser/parser_test.go
index f255934..2c5db9c 100644
--- a/docparser/parser_test.go
+++ b/docparser/parser_test.go
@@ -261,6 +261,7 @@ func TestParseNamedType(t *testing.T) {
 		})
 	}
 }
+
 func TestParseJSONTag(t *testing.T) {
 	testCases := []parseJSONTagTestCase{
 		{
@@ -403,6 +404,20 @@ func TestParseJSONTag(t *testing.T) {
 				enum:     []string{"a", "b"},
 			},
 		},
+		{
+			description: "Should parse json tag description",
+			field: &ast.Field{
+				Tag: &ast.BasicLit{
+					ValuePos: 0,
+					Kind:     0,
+					Value:    "`json:\"jsontagname\" openapi-description:\"json description of this field\"`",
+				},
+			},
+			expectedJSONTag: jsonTagInfo{
+				name:        "jsontagname",
+				description: "json description of this field",
+			},
+		},
 	}
 	for _, tc := range testCases {
 		t.Run(tc.description, func(t *testing.T) {