feat: add example parameter (#1122)

operation.go

@@ -391,6 +391,8 @@ var regexAttributes = map[string]*regexp.Regexp{
 	extensionsTag: regexp.MustCompile(`(?i)\s+extensions\(.*\)`),
 	// for collectionFormat(csv)
 	collectionFormatTag: regexp.MustCompile(`(?i)\s+collectionFormat\(.*\)`),
+	// example(0)
+	exampleTag: regexp.MustCompile(`(?i)\s+example\(.*\)`),
 }
 
 func (operation *Operation) parseAndExtractionParamAttribute(commentLine, objectType, schemaType string, param *spec.Parameter) error {
@@ -411,6 +413,8 @@ func (operation *Operation) parseAndExtractionParamAttribute(commentLine, object
 			err = setStringParam(param, attrKey, schemaType, attr, commentLine)
 		case formatTag:
 			param.Format = attr
+		case exampleTag:
+			err = setExample(param, schemaType, attr)
 		case extensionsTag:
 			_ = setExtensionParam(param, attr)
 		case collectionFormatTag:
@@ -526,6 +530,15 @@ func setDefault(param *spec.Parameter, schemaType string, value string) error {
 	return nil
 }
 
+func setExample(param *spec.Parameter, schemaType string, value string) error {
+	val, err := defineType(schemaType, value)
+	if err != nil {
+		return nil // Don't set a example value if it's not valid
+	}
+	param.Example = val
+	return nil
+}
+
 // defineType enum value define the type (object and array unsupported).
 func defineType(schemaType string, value string) (v interface{}, err error) {
 	schemaType = TransToValidSchemeType(schemaType)

operation_test.go

@@ -1821,6 +1821,67 @@ func TestParseParamCommentByDefault(t *testing.T) {
 	assert.Equal(t, expected, string(b))
 }
 
+func TestParseParamCommentByExampleInt(t *testing.T) {
+	t.Parallel()
+
+	comment := `@Param some_id query int true "Some ID" Example(10)`
+	operation := NewOperation(nil)
+	err := operation.ParseComment(comment, nil)
+
+	assert.NoError(t, err)
+	b, _ := json.MarshalIndent(operation.Parameters, "", "    ")
+	expected := `[
+    {
+        "type": "integer",
+        "example": 10,
+        "description": "Some ID",
+        "name": "some_id",
+        "in": "query",
+        "required": true
+    }
+]`
+	assert.Equal(t, expected, string(b))
+}
+
+func TestParseParamCommentByExampleString(t *testing.T) {
+	t.Parallel()
+
+	comment := `@Param some_id query string true "Some ID" Example(True feelings)`
+	operation := NewOperation(nil)
+	err := operation.ParseComment(comment, nil)
+
+	assert.NoError(t, err)
+	b, _ := json.MarshalIndent(operation.Parameters, "", "    ")
+	expected := `[
+    {
+        "type": "string",
+        "example": "True feelings",
+        "description": "Some ID",
+        "name": "some_id",
+        "in": "query",
+        "required": true
+    }
+]`
+	assert.Equal(t, expected, string(b))
+}
+
+func TestParseParamCommentByExampleUnsupportedType(t *testing.T) {
+	t.Parallel()
+	var param spec.Parameter
+
+	setExample(&param, "something", "random value")
+	assert.Equal(t, param.Example, nil)
+
+	setExample(&param, STRING, "string value")
+	assert.Equal(t, param.Example, "string value")
+
+	setExample(&param, INTEGER, "10")
+	assert.Equal(t, param.Example, 10)
+
+	setExample(&param, NUMBER, "10")
+	assert.Equal(t, param.Example, float64(10))
+}
+
 func TestParseParamArrayWithEnums(t *testing.T) {
 	t.Parallel()