// -----------------------------------------------------------------------------
// Enum Typedefs
// -----------------------------------------------------------------------------

/**
 * @typedef {"query" | "header"} ApiKeyInType
 */

/**
 * @typedef {"csv" | "ssv" | "tsv" | "pipes"} CollectionFormatType
 */

/**
 * @typedef {"binary" | "byte" | "date" | "date-time" | "double" | "float" | "int32" | "int64" | "password"} FormatType
 */

/**
 * @typedef {"string" | "number" | "integer" | "boolean" | "array"} ItemsType
 */

/**
 * @typedef {"query" | "header" | "path" | "formData" | "body"} ParameterInType
 */

/**
 * @typedef {"basic" | "apiKey" | "oauth2"} SecuritySchemeType
 */

// -----------------------------------------------------------------------------
// Model Typedefs
// -----------------------------------------------------------------------------

/**
 * @typedef {Object} Contact
 * @property {string} [name]
 * @property {string} [url]
 * @property {string} [email]
 */

/**
 * @typedef {Object} ExternalDocumentation
 * @property {string} [description]
 * @property {string} url
 */

/**
 * TODO: Can this be a union type with items?
 * @typedef {Object} Header
 * @property {string} [description]
 * @property {ItemsType} type
 * @property {FormatType} [format]
 * @property {Items} [items] NOTE: This is required if type is 'array'
 * @property {CollectionFormatType} [collectionFormat]
 * @property {Object} [default]
 * @property {number} [maximum]
 * @property {boolean} [exclusiveMaximum]
 * @property {number} [minimum]
 * @property {boolean} [exclusiveMinimum]
 * @property {number} [maxLength]
 * @property {number} [minLength]
 * @property {string} [pattern]
 * @property {number} [maxItems]
 * @property {number} [minItems]
 * @property {boolean} [uniqueItems]
 * @property {Object[]} [enum]
 * @property {number} [multipleOf]
 */

/**
 * @typedef {Object} Info
 * @property {string} title
 * @property {string} [description]
 * @property {string} [termsOfService]
 * @property {Contact} [contact]
 * @property {License} [license]
 * @property {string} version
 */

/**
 * @typedef {Object} Items
 * @property {ItemsType} type
 * @property {FormatType} [format]
 * @property {Items} [items] NOTE: This is required if type is 'array'
 * @property {CollectionFormatType} [collectionFormat]
 * @property {Object} [default]
 * @property {number} [maximum]
 * @property {boolean} [exclusiveMaximum]
 * @property {number} [minimum]
 * @property {boolean} [exclusiveMinimum]
 * @property {number} [maxLength]
 * @property {number} [minLength]
 * @property {string} [pattern]
 * @property {number} [maxItems]
 * @property {number} [minItems]
 * @property {boolean} [uniqueItems]
 * @property {Object[]} [enum]
 * @property {number} [multipleOf]
 */

/**
 * @typedef {Object} License
 * @property {string} name
 * @property {string} [url]
 */

/**
 * @typedef {Object} Operation
 * @property {string[]} [tags]
 * @property {string} [summary]
 * @property {string} [description]
 * @property {ExternalDocumentation} [externalDocs]
 * @property {string} [operationId]
 * @property {string[]} [consumes]
 * @property {string[]} [produces]
 * @property {ParameterOrRef[]} [parameters]
 * @property {Object.<string, ResponseOrRef>} responses
 * @property {string[]} [schemes]
 * @property {boolean} [deprecated]
 * @property {Object.<string, string[]>[]} [security]
 */

/**
 * TODO: This might need to be a complex union type, given the different requirements based on the &#39;in&#39; property. http://swagger.io/specification/#parameterObject
 * @typedef {Object} Parameter
 * @property {string} name
 * @property {ParameterInType} in
 * @property {string} [description]
 * @property {boolean} required
 * @property {Schema} [schema]
 * @property {string} [type]
 * @property {string} [format]
 * @property {boolean} [allowEmptyValue]
 * @property {Items} [items]
 * @property {CollectionFormatType} [collectionFormat]
 * @property {Object} [default]
 * @property {number} [maximum]
 * @property {boolean} [exclusiveMaximum]
 * @property {number} [minimum]
 * @property {boolean} [exclusiveMinimum]
 * @property {number} [maxLength]
 * @property {number} [minLength]
 * @property {string} [pattern]
 * @property {number} [maxItems]
 * @property {number} [minItems]
 * @property {boolean} [uniqueItems]
 * @property {Object[]} [enum]
 * @property {number} [multipleOf]
 */

/**
 * @typedef {Object} PathItem
 * @property {string} [ref] TODO: Needs to be named &#39;$ref&#39;
 * @property {Operation} [get]
 * @property {Operation} [put]
 * @property {Operation} [post]
 * @property {Operation} [delete]
 * @property {Operation} [options]
 * @property {Operation} [head]
 * @property {Operation} [patch]
 * @property {ParameterOrRef[]} [parameters]
 */

/**
 * @typedef {Object} Reference
 * @property {string} ref TODO: Needs to be named &#39;$ref&#39;
 */

/**
 * @typedef {Object} Response
 * @property {string} description
 * @property {Schema} [schema]
 * @property {Object.<string, Header>} [headers]
 * @property {Object} [examples]
 */

/**
 * @typedef {Object} Schema
 * @property {string} [ref] TODO: Needs to be named &#39;$ref&#39;
 * @property {FormatType} [format]
 * @property {string} [title]
 * @property {string} [description]
 * @property {Object} [default]
 * @property {number} [multipleOf]
 * @property {number} [maximum]
 * @property {boolean} [exclusiveMaximum]
 * @property {number} [minimum]
 * @property {boolean} [exclusiveMinimum]
 * @property {number} [maxLength]
 * @property {number} [minLength]
 * @property {string} [pattern]
 * @property {number} [maxItems]
 * @property {number} [minItems]
 * @property {boolean} [uniqueItems]
 * @property {number} [maxProperties]
 * @property {number} [minProperties]
 * @property {string[]} [required]
 * @property {Object[]} [enum]
 * @property {string[]} [type]
 * @property {Schema} [items] TODO: figure out if this also needs to support boolean (http://json-schema.org/latest/json-schema-validation.html#rfc.section.5.9). It&#39;s possible that a uni-directional approach may allow us to avoid supporting this odd type.
 * @property {Schema[]} [allOf]
 * @property {Object.<string, Schema>} [properties]
 * @property {Schema} [additionalProperties] TODO: figure out if this also needs to support boolean (http://json-schema.org/latest/json-schema-validation.html#rfc.section.5.18). It&#39;s possible that a uni-directional approach may allow us to avoid supporting this odd type.
 * @property {string} [discriminator]
 * @property {boolean} [readOnly]
 * @property {Xml} [xml]
 * @property {ExternalDocumentation} [externalDocs]
 * @property {Object} [example]
 */

/**
 * TODO: Consider making this a union type of the three different schemes (and their required fields)
 * @typedef {Object} SecurityScheme
 * @property {SecuritySchemeType} type
 * @property {string} [description]
 * @property {string} [name] Required for apiKey
 * @property {ApiKeyInType} [in] Required for apiKey
 * @property {string} [flow] Required for oauth2
 * @property {string} [authorizationUrl] Required for oauth2
 * @property {string} [tokenUrl] Required for oauth2
 * @property {Object.<string, string>} [scopes] Required for oauth2
 */

/**
 * @typedef {Object} Swagger
 * @property {string} swagger
 * @property {Info} info
 * @property {string} [host]
 * @property {string} [basePath]
 * @property {string[]} [schemes]
 * @property {string[]} [consumes]
 * @property {string[]} [produces]
 * @property {Object.<string, PathItem>} paths
 * @property {Object.<string, Schema>} [definitions]
 * @property {Object.<string, Parameter>} [parameters]
 * @property {Object.<string, Response>} [responses]
 * @property {Object.<string, SecurityScheme>} [securityDefinitions]
 * @property {Object.<string, string>} [security]
 * @property {Tag[]} [tags]
 * @property {ExternalDocumentation} [externalDocs]
 */

/**
 * @typedef {Object} Tag
 * @property {string} name
 * @property {string} [description]
 * @property {ExternalDocumentation} [externalDocs]
 */

/**
 * @typedef {Object} Xml
 * @property {string} [name]
 * @property {string} [namespace]
 * @property {string} [prefix]
 * @property {boolean} [attribute]
 * @property {boolean} [wrapped]
 */

// -----------------------------------------------------------------------------
// Union Typedefs
// -----------------------------------------------------------------------------

/**
 * @typedef {(Parameter & { discriminator: "parameter" } | Reference & { discriminator: "reference" })} ParameterOrRef
 */

/**
 * @typedef {(Response & { discriminator: "response" } | Reference & { discriminator: "reference" })} ResponseOrRef
 */