feat: allow to add description on struct fields using tag openapi-des…

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

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
 			}

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
 			}

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) {