niki/vendor/github.com/swaggo/swag/operation.go

package swag

import (
	"encoding/json"
	"fmt"
	"go/ast"
	goparser "go/parser"
	"go/token"
	"net/http"
	"os"
	"path/filepath"
	"regexp"
	"strconv"
	"strings"

	"github.com/go-openapi/spec"
	"golang.org/x/tools/go/loader"
)

// RouteProperties describes HTTP properties of a single router comment.

type RouteProperties struct {
	HTTPMethod string

	Path string

	Deprecated bool
}

// Operation describes a single API operation on a path.

// For more information: https://github.com/swaggo/swag#api-operation

type Operation struct {
	parser *Parser

	codeExampleFilesDir string

	spec.Operation

	RouterProperties []RouteProperties

	State string
}

var mimeTypeAliases = map[string]string{

	"json": "application/json",

	"xml": "text/xml",

	"plain": "text/plain",

	"html": "text/html",

	"mpfd": "multipart/form-data",

	"x-www-form-urlencoded": "application/x-www-form-urlencoded",

	"json-api": "application/vnd.api+json",

	"json-stream": "application/x-json-stream",

	"octet-stream": "application/octet-stream",

	"png": "image/png",

	"jpeg": "image/jpeg",

	"gif": "image/gif",
}

var mimeTypePattern = regexp.MustCompile("^[^/]+/[^/]+$")

// NewOperation creates a new Operation with default properties.

// map[int]Response.

func NewOperation(parser *Parser, options ...func(*Operation)) *Operation {

	if parser == nil {

		parser = New()

	}

	result := &Operation{

		parser: parser,

		RouterProperties: []RouteProperties{},

		Operation: spec.Operation{

			OperationProps: spec.OperationProps{

				ID: "",

				Description: "",

				Summary: "",

				Security: nil,

				ExternalDocs: nil,

				Deprecated: false,

				Tags: []string{},

				Consumes: []string{},

				Produces: []string{},

				Schemes: []string{},

				Parameters: []spec.Parameter{},

				Responses: &spec.Responses{

					VendorExtensible: spec.VendorExtensible{

						Extensions: spec.Extensions{},
					},

					ResponsesProps: spec.ResponsesProps{

						Default: nil,

						StatusCodeResponses: make(map[int]spec.Response),
					},
				},
			},

			VendorExtensible: spec.VendorExtensible{

				Extensions: spec.Extensions{},
			},
		},

		codeExampleFilesDir: "",
	}

	for _, option := range options {

		option(result)

	}

	return result

}

// SetCodeExampleFilesDirectory sets the directory to search for codeExamples.

func SetCodeExampleFilesDirectory(directoryPath string) func(*Operation) {

	return func(o *Operation) {

		o.codeExampleFilesDir = directoryPath

	}

}

// ParseComment parses comment for given comment string and returns error if error occurs.

func (operation *Operation) ParseComment(comment string, astFile *ast.File) error {

	commentLine := strings.TrimSpace(strings.TrimLeft(comment, "/"))

	if len(commentLine) == 0 {

		return nil

	}

	fields := FieldsByAnySpace(commentLine, 2)

	attribute := fields[0]

	lowerAttribute := strings.ToLower(attribute)

	var lineRemainder string

	if len(fields) > 1 {

		lineRemainder = fields[1]

	}

	switch lowerAttribute {

	case stateAttr:

		operation.ParseStateComment(lineRemainder)

	case descriptionAttr:

		operation.ParseDescriptionComment(lineRemainder)

	case descriptionMarkdownAttr:

		commentInfo, err := getMarkdownForTag(lineRemainder, operation.parser.markdownFileDir)

		if err != nil {

			return err

		}

		operation.ParseDescriptionComment(string(commentInfo))

	case summaryAttr:

		operation.Summary = lineRemainder

	case idAttr:

		operation.ID = lineRemainder

	case tagsAttr:

		operation.ParseTagsComment(lineRemainder)

	case acceptAttr:

		return operation.ParseAcceptComment(lineRemainder)

	case produceAttr:

		return operation.ParseProduceComment(lineRemainder)

	case paramAttr:

		return operation.ParseParamComment(lineRemainder, astFile)

	case successAttr, failureAttr, responseAttr:

		return operation.ParseResponseComment(lineRemainder, astFile)

	case headerAttr:

		return operation.ParseResponseHeaderComment(lineRemainder, astFile)

	case routerAttr:

		return operation.ParseRouterComment(lineRemainder, false)

	case deprecatedRouterAttr:

		return operation.ParseRouterComment(lineRemainder, true)

	case securityAttr:

		return operation.ParseSecurityComment(lineRemainder)

	case deprecatedAttr:

		operation.Deprecate()

	case xCodeSamplesAttr:

		return operation.ParseCodeSample(attribute, commentLine, lineRemainder)

	default:

		return operation.ParseMetadata(attribute, lowerAttribute, lineRemainder)

	}

	return nil

}

// ParseCodeSample parse code sample.

func (operation *Operation) ParseCodeSample(attribute, _, lineRemainder string) error {

	if lineRemainder == "file" {

		data, err := getCodeExampleForSummary(operation.Summary, operation.codeExampleFilesDir)

		if err != nil {

			return err

		}

		var valueJSON interface{}

		err = json.Unmarshal(data, &valueJSON)

		if err != nil {

			return fmt.Errorf("annotation %s need a valid json value", attribute)

		}

		// don't use the method provided by spec lib, because it will call toLower() on attribute names, which is wrongly

		operation.Extensions[attribute[1:]] = valueJSON

		return nil

	}

	// Fallback into existing logic

	return operation.ParseMetadata(attribute, strings.ToLower(attribute), lineRemainder)

}

// ParseStateComment parse state comment.

func (operation *Operation) ParseStateComment(lineRemainder string) {

	operation.State = lineRemainder

}

// ParseDescriptionComment parse description comment.

func (operation *Operation) ParseDescriptionComment(lineRemainder string) {

	if operation.Description == "" {

		operation.Description = lineRemainder

		return

	}

	operation.Description += "\n" + lineRemainder

}

// ParseMetadata parse metadata.

func (operation *Operation) ParseMetadata(attribute, lowerAttribute, lineRemainder string) error {

	// parsing specific meta data extensions

	if strings.HasPrefix(lowerAttribute, "@x-") {

		if len(lineRemainder) == 0 {

			return fmt.Errorf("annotation %s need a value", attribute)

		}

		var valueJSON interface{}

		err := json.Unmarshal([]byte(lineRemainder), &valueJSON)

		if err != nil {

			return fmt.Errorf("annotation %s need a valid json value", attribute)

		}

		// don't use the method provided by spec lib, because it will call toLower() on attribute names, which is wrongly

		operation.Extensions[attribute[1:]] = valueJSON

	}

	return nil

}

var paramPattern = regexp.MustCompile(`(\S+)\s+(\w+)\s+([\S. ]+?)\s+(\w+)\s+"([^"]+)"`)

func findInSlice(arr []string, target string) bool {

	for _, str := range arr {

		if str == target {

			return true

		}

	}

	return false

}

// ParseParamComment parses params return []string of param properties

// E.g. @Param	queryText		formData	      string	  true		        "The email for login"

//

//	[param name]    [paramType] [data type]  [is mandatory?]   [Comment]

//

// E.g. @Param   some_id     path    int     true        "Some ID".

func (operation *Operation) ParseParamComment(commentLine string, astFile *ast.File) error {

	matches := paramPattern.FindStringSubmatch(commentLine)

	if len(matches) != 6 {

		return fmt.Errorf("missing required param comment parameters \"%s\"", commentLine)

	}

	name := matches[1]

	paramType := matches[2]

	refType := TransToValidSchemeType(matches[3])

	// Detect refType

	objectType := OBJECT

	if strings.HasPrefix(refType, "[]") {

		objectType = ARRAY

		refType = strings.TrimPrefix(refType, "[]")

		refType = TransToValidSchemeType(refType)

	} else if IsPrimitiveType(refType) ||

		paramType == "formData" && refType == "file" {

		objectType = PRIMITIVE

	}

	var enums []interface{}

	if !IsPrimitiveType(refType) {

		schema, _ := operation.parser.getTypeSchema(refType, astFile, false)

		if schema != nil && len(schema.Type) == 1 && schema.Enum != nil {

			if objectType == OBJECT {

				objectType = PRIMITIVE

			}

			refType = TransToValidSchemeType(schema.Type[0])

			enums = schema.Enum

		}

	}

	requiredText := strings.ToLower(matches[4])

	required := requiredText == "true" || requiredText == requiredLabel

	description := matches[5]

	param := createParameter(paramType, description, name, objectType, refType, required, enums, operation.parser.collectionFormatInQuery)

	switch paramType {

	case "path", "header", "query", "formData":

		switch objectType {

		case ARRAY:

			if !IsPrimitiveType(refType) && !(refType == "file" && paramType == "formData") {

				return fmt.Errorf("%s is not supported array type for %s", refType, paramType)

			}

		case PRIMITIVE:

			break

		case OBJECT:

			schema, err := operation.parser.getTypeSchema(refType, astFile, false)

			if err != nil {

				return err

			}

			if len(schema.Properties) == 0 {

				return nil

			}

			items := schema.Properties.ToOrderedSchemaItems()

			for _, item := range items {

				name, prop := item.Name, &item.Schema

				if len(prop.Type) == 0 {

					prop = operation.parser.getUnderlyingSchema(prop)

					if len(prop.Type) == 0 {

						continue

					}

				}

				nameOverrideType := paramType

				// query also uses formData tags

				if paramType == "query" {

					nameOverrideType = "formData"

				}

				// load overridden type specific name from extensions if exists

				if nameVal, ok := item.Schema.Extensions[nameOverrideType]; ok {

					name = nameVal.(string)

				}

				switch {

				case prop.Type[0] == ARRAY:

					if prop.Items.Schema == nil {

						continue

					}

					itemSchema := prop.Items.Schema

					if len(itemSchema.Type) == 0 {

						itemSchema = operation.parser.getUnderlyingSchema(prop.Items.Schema)

					}

					if len(itemSchema.Type) == 0 {

						continue

					}

					if !IsSimplePrimitiveType(itemSchema.Type[0]) {

						continue

					}

					param = createParameter(paramType, prop.Description, name, prop.Type[0], itemSchema.Type[0], findInSlice(schema.Required, item.Name), itemSchema.Enum, operation.parser.collectionFormatInQuery)

				case IsSimplePrimitiveType(prop.Type[0]):

					param = createParameter(paramType, prop.Description, name, PRIMITIVE, prop.Type[0], findInSlice(schema.Required, item.Name), nil, operation.parser.collectionFormatInQuery)

				default:

					operation.parser.debug.Printf("skip field [%s] in %s is not supported type for %s", name, refType, paramType)

					continue

				}

				param.Nullable = prop.Nullable

				param.Format = prop.Format

				param.Default = prop.Default

				param.Example = prop.Example

				param.Extensions = prop.Extensions

				param.CommonValidations.Maximum = prop.Maximum

				param.CommonValidations.Minimum = prop.Minimum

				param.CommonValidations.ExclusiveMaximum = prop.ExclusiveMaximum

				param.CommonValidations.ExclusiveMinimum = prop.ExclusiveMinimum

				param.CommonValidations.MaxLength = prop.MaxLength

				param.CommonValidations.MinLength = prop.MinLength

				param.CommonValidations.Pattern = prop.Pattern

				param.CommonValidations.MaxItems = prop.MaxItems

				param.CommonValidations.MinItems = prop.MinItems

				param.CommonValidations.UniqueItems = prop.UniqueItems

				param.CommonValidations.MultipleOf = prop.MultipleOf

				param.CommonValidations.Enum = prop.Enum

				operation.Operation.Parameters = append(operation.Operation.Parameters, param)

			}

			return nil

		}

	case "body":

		if objectType == PRIMITIVE {

			param.Schema = PrimitiveSchema(refType)

		} else {

			schema, err := operation.parseAPIObjectSchema(commentLine, objectType, refType, astFile)

			if err != nil {

				return err

			}

			param.Schema = schema

		}

	default:

		return fmt.Errorf("%s is not supported paramType", paramType)

	}

	err := operation.parseParamAttribute(commentLine, objectType, refType, paramType, &param)

	if err != nil {

		return err

	}

	operation.Operation.Parameters = append(operation.Operation.Parameters, param)

	return nil

}

const (
	formTag = "form"

	jsonTag = "json"

	uriTag = "uri"

	headerTag = "header"

	bindingTag = "binding"

	defaultTag = "default"

	enumsTag = "enums"

	exampleTag = "example"

	schemaExampleTag = "schemaExample"

	formatTag = "format"

	validateTag = "validate"

	minimumTag = "minimum"

	maximumTag = "maximum"

	minLengthTag = "minLength"

	maxLengthTag = "maxLength"

	multipleOfTag = "multipleOf"

	readOnlyTag = "readonly"

	extensionsTag = "extensions"

	collectionFormatTag = "collectionFormat"
)

var regexAttributes = map[string]*regexp.Regexp{

	// for Enums(A, B)

	enumsTag: regexp.MustCompile(`(?i)\s+enums\(.*\)`),

	// for maximum(0)

	maximumTag: regexp.MustCompile(`(?i)\s+maxinum|maximum\(.*\)`),

	// for minimum(0)

	minimumTag: regexp.MustCompile(`(?i)\s+mininum|minimum\(.*\)`),

	// for default(0)

	defaultTag: regexp.MustCompile(`(?i)\s+default\(.*\)`),

	// for minlength(0)

	minLengthTag: regexp.MustCompile(`(?i)\s+minlength\(.*\)`),

	// for maxlength(0)

	maxLengthTag: regexp.MustCompile(`(?i)\s+maxlength\(.*\)`),

	// for format(email)

	formatTag: regexp.MustCompile(`(?i)\s+format\(.*\)`),

	// for extensions(x-example=test)

	extensionsTag: regexp.MustCompile(`(?i)\s+extensions\(.*\)`),

	// for collectionFormat(csv)

	collectionFormatTag: regexp.MustCompile(`(?i)\s+collectionFormat\(.*\)`),

	// example(0)

	exampleTag: regexp.MustCompile(`(?i)\s+example\(.*\)`),

	// schemaExample(0)

	schemaExampleTag: regexp.MustCompile(`(?i)\s+schemaExample\(.*\)`),
}

func (operation *Operation) parseParamAttribute(comment, objectType, schemaType, paramType string, param *spec.Parameter) error {

	schemaType = TransToValidSchemeType(schemaType)

	for attrKey, re := range regexAttributes {

		attr, err := findAttr(re, comment)

		if err != nil {

			continue

		}

		switch attrKey {

		case enumsTag:

			err = setEnumParam(param, attr, objectType, schemaType, paramType)

		case minimumTag, maximumTag:

			err = setNumberParam(param, attrKey, schemaType, attr, comment)

		case defaultTag:

			err = setDefault(param, schemaType, attr)

		case minLengthTag, maxLengthTag:

			err = setStringParam(param, attrKey, schemaType, attr, comment)

		case formatTag:

			param.Format = attr

		case exampleTag:

			err = setExample(param, schemaType, attr)

		case schemaExampleTag:

			err = setSchemaExample(param, schemaType, attr)

		case extensionsTag:

			param.Extensions = setExtensionParam(attr)

		case collectionFormatTag:

			err = setCollectionFormatParam(param, attrKey, objectType, attr, comment)

		}

		if err != nil {

			return err

		}

	}

	return nil

}

func findAttr(re *regexp.Regexp, commentLine string) (string, error) {

	attr := re.FindString(commentLine)

	l, r := strings.Index(attr, "("), strings.Index(attr, ")")

	if l == -1 || r == -1 {

		return "", fmt.Errorf("can not find regex=%s, comment=%s", re.String(), commentLine)

	}

	return strings.TrimSpace(attr[l+1 : r]), nil

}

func setStringParam(param *spec.Parameter, name, schemaType, attr, commentLine string) error {

	if schemaType != STRING {

		return fmt.Errorf("%s is attribute to set to a number. comment=%s got=%s", name, commentLine, schemaType)

	}

	n, err := strconv.ParseInt(attr, 10, 64)

	if err != nil {

		return fmt.Errorf("%s is allow only a number got=%s", name, attr)

	}

	switch name {

	case minLengthTag:

		param.MinLength = &n

	case maxLengthTag:

		param.MaxLength = &n

	}

	return nil

}

func setNumberParam(param *spec.Parameter, name, schemaType, attr, commentLine string) error {

	switch schemaType {

	case INTEGER, NUMBER:

		n, err := strconv.ParseFloat(attr, 64)

		if err != nil {

			return fmt.Errorf("maximum is allow only a number. comment=%s got=%s", commentLine, attr)

		}

		switch name {

		case minimumTag:

			param.Minimum = &n

		case maximumTag:

			param.Maximum = &n

		}

		return nil

	default:

		return fmt.Errorf("%s is attribute to set to a number. comment=%s got=%s", name, commentLine, schemaType)

	}

}

func setEnumParam(param *spec.Parameter, attr, objectType, schemaType, paramType string) error {

	for _, e := range strings.Split(attr, ",") {

		e = strings.TrimSpace(e)

		value, err := defineType(schemaType, e)

		if err != nil {

			return err

		}

		switch objectType {

		case ARRAY:

			param.Items.Enum = append(param.Items.Enum, value)

		default:

			switch paramType {

			case "body":

				param.Schema.Enum = append(param.Schema.Enum, value)

			default:

				param.Enum = append(param.Enum, value)

			}

		}

	}

	return nil

}

func setExtensionParam(attr string) spec.Extensions {

	extensions := spec.Extensions{}

	for _, val := range splitNotWrapped(attr, ',') {

		parts := strings.SplitN(val, "=", 2)

		if len(parts) == 2 {

			extensions.Add(parts[0], parts[1])

			continue

		}

		if len(parts[0]) > 0 && string(parts[0][0]) == "!" {

			extensions.Add(parts[0][1:], false)

			continue

		}

		extensions.Add(parts[0], true)

	}

	return extensions

}

func setCollectionFormatParam(param *spec.Parameter, name, schemaType, attr, commentLine string) error {

	if schemaType == ARRAY {

		param.CollectionFormat = TransToValidCollectionFormat(attr)

		return nil

	}

	return fmt.Errorf("%s is attribute to set to an array. comment=%s got=%s", name, commentLine, schemaType)

}

func setDefault(param *spec.Parameter, schemaType string, value string) error {

	val, err := defineType(schemaType, value)

	if err != nil {

		return nil // Don't set a default value if it's not valid

	}

	param.Default = val

	return nil

}

func setSchemaExample(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

	}

	// skip schema

	if param.Schema == nil {

		return nil

	}

	switch v := val.(type) {

	case string:

		//  replaces \r \n \t in example string values.

		param.Schema.Example = strings.NewReplacer(`\r`, "\r", `\n`, "\n", `\t`, "\t").Replace(v)

	default:

		param.Schema.Example = val

	}

	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)

	switch schemaType {

	case STRING:

		return value, nil

	case NUMBER:

		v, err = strconv.ParseFloat(value, 64)

		if err != nil {

			return nil, fmt.Errorf("enum value %s can't convert to %s err: %s", value, schemaType, err)

		}

	case INTEGER:

		v, err = strconv.Atoi(value)

		if err != nil {

			return nil, fmt.Errorf("enum value %s can't convert to %s err: %s", value, schemaType, err)

		}

	case BOOLEAN:

		v, err = strconv.ParseBool(value)

		if err != nil {

			return nil, fmt.Errorf("enum value %s can't convert to %s err: %s", value, schemaType, err)

		}

	default:

		return nil, fmt.Errorf("%s is unsupported type in enum value %s", schemaType, value)

	}

	return v, nil

}

// ParseTagsComment parses comment for given `tag` comment string.

func (operation *Operation) ParseTagsComment(commentLine string) {

	for _, tag := range strings.Split(commentLine, ",") {

		operation.Tags = append(operation.Tags, strings.TrimSpace(tag))

	}

}

// ParseAcceptComment parses comment for given `accept` comment string.

func (operation *Operation) ParseAcceptComment(commentLine string) error {

	return parseMimeTypeList(commentLine, &operation.Consumes, "%v accept type can't be accepted")

}

// ParseProduceComment parses comment for given `produce` comment string.

func (operation *Operation) ParseProduceComment(commentLine string) error {

	return parseMimeTypeList(commentLine, &operation.Produces, "%v produce type can't be accepted")

}

// parseMimeTypeList parses a list of MIME Types for a comment like

// `produce` (`Content-Type:` response header) or

// `accept` (`Accept:` request header).

func parseMimeTypeList(mimeTypeList string, typeList *[]string, format string) error {

	for _, typeName := range strings.Split(mimeTypeList, ",") {

		if mimeTypePattern.MatchString(typeName) {

			*typeList = append(*typeList, typeName)

			continue

		}

		aliasMimeType, ok := mimeTypeAliases[typeName]

		if !ok {

			return fmt.Errorf(format, typeName)

		}

		*typeList = append(*typeList, aliasMimeType)

	}

	return nil

}

var routerPattern = regexp.MustCompile(`^(/[\w./\-{}+:$]*)[[:blank:]]+\[(\w+)]`)

// ParseRouterComment parses comment for given `router` comment string.

func (operation *Operation) ParseRouterComment(commentLine string, deprecated bool) error {

	matches := routerPattern.FindStringSubmatch(commentLine)

	if len(matches) != 3 {

		return fmt.Errorf("can not parse router comment \"%s\"", commentLine)

	}

	signature := RouteProperties{

		Path: matches[1],

		HTTPMethod: strings.ToUpper(matches[2]),

		Deprecated: deprecated,
	}

	if _, ok := allMethod[signature.HTTPMethod]; !ok {

		return fmt.Errorf("invalid method: %s", signature.HTTPMethod)

	}

	operation.RouterProperties = append(operation.RouterProperties, signature)

	return nil

}

// ParseSecurityComment parses comment for given `security` comment string.

func (operation *Operation) ParseSecurityComment(commentLine string) error {

	if len(commentLine) == 0 {

		operation.Security = []map[string][]string{}

		return nil

	}

	var (
		securityMap = make(map[string][]string)

		securitySource = commentLine[strings.Index(commentLine, "@Security")+1:]
	)

	for _, securityOption := range strings.Split(securitySource, "||") {

		securityOption = strings.TrimSpace(securityOption)

		left, right := strings.Index(securityOption, "["), strings.Index(securityOption, "]")

		if !(left == -1 && right == -1) {

			scopes := securityOption[left+1 : right]

			var options []string

			for _, scope := range strings.Split(scopes, ",") {

				options = append(options, strings.TrimSpace(scope))

			}

			securityKey := securityOption[0:left]

			securityMap[securityKey] = append(securityMap[securityKey], options...)

		} else {

			securityKey := strings.TrimSpace(securityOption)

			securityMap[securityKey] = []string{}

		}

	}

	operation.Security = append(operation.Security, securityMap)

	return nil

}

// findTypeDef attempts to find the *ast.TypeSpec for a specific type given the

// type's name and the package's import path.

// TODO: improve finding external pkg.

func findTypeDef(importPath, typeName string) (*ast.TypeSpec, error) {

	cwd, err := os.Getwd()

	if err != nil {

		return nil, err

	}

	conf := loader.Config{

		ParserMode: goparser.SpuriousErrors,

		Cwd: cwd,
	}

	conf.Import(importPath)

	lprog, err := conf.Load()

	if err != nil {

		return nil, err

	}

	// If the pkg is vendored, the actual pkg path is going to resemble

	// something like "{importPath}/vendor/{importPath}"

	for k := range lprog.AllPackages {

		realPkgPath := k.Path()

		if strings.Contains(realPkgPath, "vendor/"+importPath) {

			importPath = realPkgPath

		}

	}

	pkgInfo := lprog.Package(importPath)

	if pkgInfo == nil {

		return nil, fmt.Errorf("package was nil")

	}

	// TODO: possibly cache pkgInfo since it's an expensive operation

	for i := range pkgInfo.Files {

		for _, astDeclaration := range pkgInfo.Files[i].Decls {

			generalDeclaration, ok := astDeclaration.(*ast.GenDecl)

			if ok && generalDeclaration.Tok == token.TYPE {

				for _, astSpec := range generalDeclaration.Specs {

					typeSpec, ok := astSpec.(*ast.TypeSpec)

					if ok {

						if typeSpec.Name.String() == typeName {

							return typeSpec, nil

						}

					}

				}

			}

		}

	}

	return nil, fmt.Errorf("type spec not found")

}

var responsePattern = regexp.MustCompile(`^([\w,]+)\s+([\w{}]+)\s+([\w\-.\\{}=,\[\s\]]+)\s*(".*)?`)

// ResponseType{data1=Type1,data2=Type2}.

var combinedPattern = regexp.MustCompile(`^([\w\-./\[\]]+){(.*)}$`)

func (operation *Operation) parseObjectSchema(refType string, astFile *ast.File) (*spec.Schema, error) {

	return parseObjectSchema(operation.parser, refType, astFile)

}

func parseObjectSchema(parser *Parser, refType string, astFile *ast.File) (*spec.Schema, error) {

	switch {

	case refType == NIL:

		return nil, nil

	case refType == INTERFACE:

		return PrimitiveSchema(OBJECT), nil

	case refType == ANY:

		return PrimitiveSchema(OBJECT), nil

	case IsGolangPrimitiveType(refType):

		refType = TransToValidSchemeType(refType)

		return PrimitiveSchema(refType), nil

	case IsPrimitiveType(refType):

		return PrimitiveSchema(refType), nil

	case strings.HasPrefix(refType, "[]"):

		schema, err := parseObjectSchema(parser, refType[2:], astFile)

		if err != nil {

			return nil, err

		}

		return spec.ArrayProperty(schema), nil

	case strings.HasPrefix(refType, "map["):

		// ignore key type

		idx := strings.Index(refType, "]")

		if idx < 0 {

			return nil, fmt.Errorf("invalid type: %s", refType)

		}

		refType = refType[idx+1:]

		if refType == INTERFACE || refType == ANY {

			return spec.MapProperty(nil), nil

		}

		schema, err := parseObjectSchema(parser, refType, astFile)

		if err != nil {

			return nil, err

		}

		return spec.MapProperty(schema), nil

	case strings.Contains(refType, "{"):

		return parseCombinedObjectSchema(parser, refType, astFile)

	default:

		if parser != nil { // checking refType has existing in 'TypeDefinitions'

			schema, err := parser.getTypeSchema(refType, astFile, true)

			if err != nil {

				return nil, err

			}

			return schema, nil

		}

		return RefSchema(refType), nil

	}

}

func parseFields(s string) []string {

	nestLevel := 0

	return strings.FieldsFunc(s, func(char rune) bool {

		if char == '{' {

			nestLevel++

			return false

		} else if char == '}' {

			nestLevel--

			return false

		}

		return char == ',' && nestLevel == 0

	})

}

func parseCombinedObjectSchema(parser *Parser, refType string, astFile *ast.File) (*spec.Schema, error) {

	matches := combinedPattern.FindStringSubmatch(refType)

	if len(matches) != 3 {

		return nil, fmt.Errorf("invalid type: %s", refType)

	}

	schema, err := parseObjectSchema(parser, matches[1], astFile)

	if err != nil {

		return nil, err

	}

	fields, props := parseFields(matches[2]), map[string]spec.Schema{}

	for _, field := range fields {

		keyVal := strings.SplitN(field, "=", 2)

		if len(keyVal) == 2 {

			schema, err := parseObjectSchema(parser, keyVal[1], astFile)

			if err != nil {

				return nil, err

			}

			if schema == nil {

				schema = PrimitiveSchema(OBJECT)

			}

			props[keyVal[0]] = *schema

		}

	}

	if len(props) == 0 {

		return schema, nil

	}

	if schema.Ref.GetURL() == nil && len(schema.Type) > 0 && schema.Type[0] == OBJECT && len(schema.Properties) == 0 && schema.AdditionalProperties == nil {

		schema.Properties = props

		return schema, nil

	}

	return spec.ComposedSchema(*schema, spec.Schema{

		SchemaProps: spec.SchemaProps{

			Type: []string{OBJECT},

			Properties: props,
		},
	}), nil

}

func (operation *Operation) parseAPIObjectSchema(commentLine, schemaType, refType string, astFile *ast.File) (*spec.Schema, error) {

	if strings.HasSuffix(refType, ",") && strings.Contains(refType, "[") {

		// regexp may have broken generic syntax. find closing bracket and add it back

		allMatchesLenOffset := strings.Index(commentLine, refType) + len(refType)

		lostPartEndIdx := strings.Index(commentLine[allMatchesLenOffset:], "]")

		if lostPartEndIdx >= 0 {

			refType += commentLine[allMatchesLenOffset : allMatchesLenOffset+lostPartEndIdx+1]

		}

	}

	switch schemaType {

	case OBJECT:

		if !strings.HasPrefix(refType, "[]") {

			return operation.parseObjectSchema(refType, astFile)

		}

		refType = refType[2:]

		fallthrough

	case ARRAY:

		schema, err := operation.parseObjectSchema(refType, astFile)

		if err != nil {

			return nil, err

		}

		return spec.ArrayProperty(schema), nil

	default:

		return PrimitiveSchema(schemaType), nil

	}

}

// ParseResponseComment parses comment for given `response` comment string.

func (operation *Operation) ParseResponseComment(commentLine string, astFile *ast.File) error {

	matches := responsePattern.FindStringSubmatch(commentLine)

	if len(matches) != 5 {

		err := operation.ParseEmptyResponseComment(commentLine)

		if err != nil {

			return operation.ParseEmptyResponseOnly(commentLine)

		}

		return err

	}

	description := strings.Trim(matches[4], "\"")

	schema, err := operation.parseAPIObjectSchema(commentLine, strings.Trim(matches[2], "{}"), strings.TrimSpace(matches[3]), astFile)

	if err != nil {

		return err

	}

	for _, codeStr := range strings.Split(matches[1], ",") {

		if strings.EqualFold(codeStr, defaultTag) {

			operation.DefaultResponse().WithSchema(schema).WithDescription(description)

			continue

		}

		code, err := strconv.Atoi(codeStr)

		if err != nil {

			return fmt.Errorf("can not parse response comment \"%s\"", commentLine)

		}

		resp := spec.NewResponse().WithSchema(schema).WithDescription(description)

		if description == "" {

			resp.WithDescription(http.StatusText(code))

		}

		operation.AddResponse(code, resp)

	}

	return nil

}

func newHeaderSpec(schemaType, description string) spec.Header {

	return spec.Header{

		SimpleSchema: spec.SimpleSchema{

			Type: schemaType,
		},

		HeaderProps: spec.HeaderProps{

			Description: description,
		},

		VendorExtensible: spec.VendorExtensible{

			Extensions: nil,
		},

		CommonValidations: spec.CommonValidations{

			Maximum: nil,

			ExclusiveMaximum: false,

			Minimum: nil,

			ExclusiveMinimum: false,

			MaxLength: nil,

			MinLength: nil,

			Pattern: "",

			MaxItems: nil,

			MinItems: nil,

			UniqueItems: false,

			MultipleOf: nil,

			Enum: nil,
		},
	}

}

// ParseResponseHeaderComment parses comment for given `response header` comment string.

func (operation *Operation) ParseResponseHeaderComment(commentLine string, _ *ast.File) error {

	matches := responsePattern.FindStringSubmatch(commentLine)

	if len(matches) != 5 {

		return fmt.Errorf("can not parse response comment \"%s\"", commentLine)

	}

	header := newHeaderSpec(strings.Trim(matches[2], "{}"), strings.Trim(matches[4], "\""))

	headerKey := strings.TrimSpace(matches[3])

	if strings.EqualFold(matches[1], "all") {

		if operation.Responses.Default != nil {

			operation.Responses.Default.Headers[headerKey] = header

		}

		if operation.Responses.StatusCodeResponses != nil {

			for code, response := range operation.Responses.StatusCodeResponses {

				response.Headers[headerKey] = header

				operation.Responses.StatusCodeResponses[code] = response

			}

		}

		return nil

	}

	for _, codeStr := range strings.Split(matches[1], ",") {

		if strings.EqualFold(codeStr, defaultTag) {

			if operation.Responses.Default != nil {

				operation.Responses.Default.Headers[headerKey] = header

			}

			continue

		}

		code, err := strconv.Atoi(codeStr)

		if err != nil {

			return fmt.Errorf("can not parse response comment \"%s\"", commentLine)

		}

		if operation.Responses.StatusCodeResponses != nil {

			response, responseExist := operation.Responses.StatusCodeResponses[code]

			if responseExist {

				response.Headers[headerKey] = header

				operation.Responses.StatusCodeResponses[code] = response

			}

		}

	}

	return nil

}

var emptyResponsePattern = regexp.MustCompile(`([\w,]+)\s+"(.*)"`)

// ParseEmptyResponseComment parse only comment out status code and description,eg: @Success 200 "it's ok".

func (operation *Operation) ParseEmptyResponseComment(commentLine string) error {

	matches := emptyResponsePattern.FindStringSubmatch(commentLine)

	if len(matches) != 3 {

		return fmt.Errorf("can not parse response comment \"%s\"", commentLine)

	}

	description := strings.Trim(matches[2], "\"")

	for _, codeStr := range strings.Split(matches[1], ",") {

		if strings.EqualFold(codeStr, defaultTag) {

			operation.DefaultResponse().WithDescription(description)

			continue

		}

		code, err := strconv.Atoi(codeStr)

		if err != nil {

			return fmt.Errorf("can not parse response comment \"%s\"", commentLine)

		}

		operation.AddResponse(code, spec.NewResponse().WithDescription(description))

	}

	return nil

}

// ParseEmptyResponseOnly parse only comment out status code ,eg: @Success 200.

func (operation *Operation) ParseEmptyResponseOnly(commentLine string) error {

	for _, codeStr := range strings.Split(commentLine, ",") {

		if strings.EqualFold(codeStr, defaultTag) {

			_ = operation.DefaultResponse()

			continue

		}

		code, err := strconv.Atoi(codeStr)

		if err != nil {

			return fmt.Errorf("can not parse response comment \"%s\"", commentLine)

		}

		operation.AddResponse(code, spec.NewResponse().WithDescription(http.StatusText(code)))

	}

	return nil

}

// DefaultResponse return the default response member pointer.

func (operation *Operation) DefaultResponse() *spec.Response {

	if operation.Responses.Default == nil {

		operation.Responses.Default = &spec.Response{

			ResponseProps: spec.ResponseProps{

				Description: "",

				Headers: make(map[string]spec.Header),
			},
		}

	}

	return operation.Responses.Default

}

// AddResponse add a response for a code.

func (operation *Operation) AddResponse(code int, response *spec.Response) {

	if response.Headers == nil {

		response.Headers = make(map[string]spec.Header)

	}

	operation.Responses.StatusCodeResponses[code] = *response

}

// createParameter returns swagger spec.Parameter for given  paramType, description, paramName, schemaType, required.

func createParameter(paramType, description, paramName, objectType, schemaType string, required bool, enums []interface{}, collectionFormat string) spec.Parameter {

	// //five possible parameter types. 	query, path, body, header, form

	result := spec.Parameter{

		ParamProps: spec.ParamProps{

			Name: paramName,

			Description: description,

			Required: required,

			In: paramType,
		},
	}

	if paramType == "body" {

		return result

	}

	switch objectType {

	case ARRAY:

		result.Type = objectType

		result.CollectionFormat = collectionFormat

		result.Items = &spec.Items{

			CommonValidations: spec.CommonValidations{

				Enum: enums,
			},

			SimpleSchema: spec.SimpleSchema{

				Type: schemaType,
			},
		}

	case PRIMITIVE, OBJECT:

		result.Type = schemaType

		result.Enum = enums

	}

	return result

}

func getCodeExampleForSummary(summaryName string, dirPath string) ([]byte, error) {

	dirEntries, err := os.ReadDir(dirPath)

	if err != nil {

		return nil, err

	}

	for _, entry := range dirEntries {

		if entry.IsDir() {

			continue

		}

		fileName := entry.Name()

		if !strings.Contains(fileName, ".json") {

			continue

		}

		if strings.Contains(fileName, summaryName) {

			fullPath := filepath.Join(dirPath, fileName)

			commentInfo, err := os.ReadFile(fullPath)

			if err != nil {

				return nil, fmt.Errorf("Failed to read code example file %s error: %s ", fullPath, err)

			}

			return commentInfo, nil

		}

	}

	return nil, fmt.Errorf("unable to find code example file for tag %s in the given directory", summaryName)

}