import type { Examples } from "./example";
import type { Extension } from "./extensions";
import type { ExternalDocumentation } from "./externalDocs";
import type { BaseReference } from "./references";
import type { Schema } from "./schema";
import type { ResponsesMap } from "./status";

/**
 * Path Item Object
 *
 * Describes the operations available on a single path. A Path Item may be empty,
 * due to ACL constraints. The path itself is still exposed to the documentation
 * viewer but they will not know which operations and parameters are available.
 *
 * @see https://swagger.io/specification/v2/#path-item-object
 * @example
 * ```typescript
 * const pathItem: PathItem = {
 *   get: {
 *     summary: "Get users",
 *     operationId: "getUsers",
 *     responses: {
 *       "200": {
 *         description: "List of users",
 *         schema: { type: "array", items: { $ref: "#/definitions/User" } }
 *       }
 *     }
 *   },
 *   post: {
 *     summary: "Create user",
 *     operationId: "createUser",
 *     parameters: [
 *       {
 *         name: "user",
 *         in: "body",
 *         schema: { $ref: "#/definitions/User" }
 *       }
 *     ],
 *     responses: {
 *       "201": {
 *         description: "User created",
 *         schema: { $ref: "#/definitions/User" }
 *       }
 *     }
 *   },
 *   parameters: [
 *     {
 *       name: "limit",
 *       in: "query",
 *       type: "integer",
 *       description: "Maximum number of items to return"
 *     }
 *   ]
 * }
 * ```
 */
export type PathItem =
  | ({
      /**
       * A definition of a GET operation on this path.
       *
       * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - get}
       *
       * @example { summary: "Get users", responses: { "200": { description: "Success" } } }
       */
      get?: Operation;

      /**
       * A definition of a PUT operation on this path.
       *
       * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - put}
       *
       * @example { summary: "Update user", responses: { "200": { description: "Success" } } }
       */
      put?: Operation;

      /**
       * A definition of a POST operation on this path.
       *
       * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - post}
       *
       * @example { summary: "Create user", responses: { "201": { description: "Created" } } }
       */
      post?: Operation;

      /**
       * A definition of a DELETE operation on this path.
       *
       * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - delete}
       *
       * @example { summary: "Delete user", responses: { "204": { description: "No Content" } } }
       */
      delete?: Operation;

      /**
       * A definition of an OPTIONS operation on this path.
       *
       * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - options}
       *
       * @example { summary: "Get options", responses: { "200": { description: "Options" } } }
       */
      options?: Operation;

      /**
       * A definition of a HEAD operation on this path.
       *
       * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - head}
       *
       * @example { summary: "Check if resource exists", responses: { "200": { description: "Exists" } } }
       */
      head?: Operation;

      /**
       * A definition of a PATCH operation on this path.
       *
       * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - patch}
       *
       * @example { summary: "Partially update user", responses: { "200": { description: "Success" } } }
       */
      patch?: Operation;

      /**
       * A list of parameters that are applicable for all the operations described
       * under this path. These parameters can be overridden at the operation level,
       * but cannot be removed there. The list MUST NOT include duplicated parameters.
       * A unique parameter is defined by a combination of a name and location.
       *
       * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - parameters}
       *
       * @example [{ name: "limit", in: "query", type: "integer" }]
       */
      parameters?: Array<Parameter | BaseReference>;
    } & Extension)
  | BaseReference;

/**
 * Operation Object
 *
 * Describes a single API operation on a path. A unique operation is defined
 * by a combination of a path and an HTTP method.
 *
 * @see https://swagger.io/specification/v2/#operation-object
 * @example
 * ```typescript
 * const operation: Operation = {
 *   tags: ["users"],
 *   summary: "Get user by ID",
 *   description: "Retrieves a specific user by their unique identifier",
 *   operationId: "getUserById",
 *   consumes: ["application/json"],
 *   produces: ["application/json"],
 *   parameters: [
 *     {
 *       name: "id",
 *       in: "path",
 *       required: true,
 *       type: "string",
 *       description: "The user ID"
 *     }
 *   ],
 *   responses: {
 *     "200": {
 *       description: "User found",
 *       schema: { $ref: "#/definitions/User" }
 *     },
 *     "404": {
 *       description: "User not found"
 *     }
 *   },
 *   deprecated: false,
 *   security: [{ "api_key": [] }]
 * }
 * ```
 */
export interface Operation extends Extension {
  /**
   * A list of tags for API documentation control. Tags can be used for logical
   * grouping of operations by resources or any other qualifier.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - tags}
   *
   * @example ["users", "authentication"]
   * @example ["pets"]
   */
  tags?: string[];

  /**
   * A short summary of what the operation does. For maximum readability in
   * swagger-ui, this field SHOULD be less than 120 characters.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - summary}
   *
   * @example "Get user by ID"
   * @example "Create a new pet"
   */
  summary?: string;

  /**
   * A verbose explanation of the operation behavior. GFM syntax can be used
   * for rich text representation.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - description}
   *
   * @example "Retrieves a specific user by their unique identifier. Returns user details including name, email, and profile information."
   */
  description?: string;

  /**
   * Additional external documentation for this operation.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - externalDocs}
   *
   * @example { description: "Find out more about this operation", url: "https://example.com/docs" }
   */
  externalDocs?: ExternalDocumentation;

  /**
   * Unique string used to identify the operation. The id MUST be unique among
   * all operations described in the API. Tools and libraries MAY use the
   * operationId to uniquely identify an operation, therefore, it is recommended
   * to follow common programming naming conventions.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - operationId}
   *
   * @example "getUserById"
   * @example "createPet"
   */
  operationId?: string;

  /**
   * A list of MIME types the operation can consume. This overrides the consumes
   * definition at the Swagger Object level. An empty value MAY be used to clear
   * the global definition. Value MUST be as described under Mime Types.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - consumes}
   *
   * @example ["application/json"]
   * @example ["application/xml", "application/json"]
   */
  consumes?: string[];

  /**
   * A list of MIME types the operation can produce. This overrides the produces
   * definition at the Swagger Object level. An empty value MAY be used to clear
   * the global definition. Value MUST be as described under Mime Types.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - produces}
   *
   * @example ["application/json"]
   * @example ["application/xml", "application/json"]
   */
  produces?: string[];

  /**
   * A list of parameters that are applicable for this operation. If a parameter
   * is already defined at the Path Item, the new definition will override it
   * but can never remove it. The list MUST NOT include duplicated parameters.
   * A unique parameter is defined by a combination of a name and location.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - parameters}
   *
   * @example [{ name: "id", in: "path", required: true, type: "string" }]
   */
  parameters?: Array<Parameter | BaseReference>;

  /**
   * The list of possible responses as they are returned from executing this operation.
   * This field MUST be present and MUST contain at least one response.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - responses}
   *
   * @example { "200": { description: "Success", schema: { type: "object" } } }
   */
  responses: ResponsesMap;

  /**
   * The transfer protocol for the operation. Values MUST be from the list:
   * "http", "https", "ws", "wss". The value overrides the Swagger Object
   * schemes definition.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - schemes}
   *
   * @example ["https", "http"]
   * @example ["wss"]
   */
  schemes?: Array<"http" | "https" | "ws" | "wss">;

  /**
   * Declares this operation to be deprecated. Usage of the declared operation
   * should be refrained. Default value is false.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - deprecated}
   *
   * @default false
   * @example true
   */
  deprecated?: boolean;

  /**
   * A declaration of which security schemes are applied for this operation.
   * The list of values describes alternative security schemes that can be used
   * (that is, there is a logical OR between the security requirements).
   * This definition overrides any declared top-level security. To remove a
   * top-level security declaration, an empty array can be used.
   *
   * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - security}
   *
   * @example [{ "api_key": [] }]
   * @example [{ "oauth2": ["read", "write"] }]
   */
  security?: Array<Record<string, string[]>>;
}

/**
 * Parameter Object
 *
 * Describes a single operation parameter. A unique parameter is defined by a
 * combination of a name and location.
 *
 * @see https://swagger.io/specification/v2/#parameter-object
 * @example
 * ```typescript
 * // Query parameter
 * const queryParam: Parameter = {
 *   name: "limit",
 *   in: "query",
 *   description: "Maximum number of items to return",
 *   required: false,
 *   type: "integer",
 *   format: "int32"
 * }
 *
 * // Path parameter
 * const pathParam: Parameter = {
 *   name: "id",
 *   in: "path",
 *   description: "The user ID",
 *   required: true,
 *   type: "string"
 * }
 *
 * // Body parameter
 * const bodyParam: Parameter = {
 *   name: "user",
 *   in: "body",
 *   description: "User object to create",
 *   required: true,
 *   schema: { $ref: "#/definitions/User" }
 * }
 * ```
 */
/**
 * -----
 * Parameter Object (Body Parameter)
 * -----
 *
 * Describes a body parameter for an API operation. Body parameters represent
 * the payload that's appended to the HTTP request. Since there can only be one
 * payload, there can only be one body parameter per operation.
 *
 * Body parameters use a schema to define the structure of the request payload,
 * which can be any valid Swagger schema including objects, arrays, and primitives.
 *
 * | Version | Reference |
 * |---|-----|
 * | 2.0     | {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Parameter Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `name` - The name of the parameter (used for documentation purposes only)
 * @property `in` - Must be "body" for body parameters
 * @property `description` - A brief description of the parameter
 * @property `required` - Whether the parameter is mandatory
 * @property `schema` - The schema defining the type used for the body parameter (required)
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * Body parameters are mutually exclusive with form parameters for the same operation.
 * The schema property is required for body parameters.
 *
 * -----
 * Examples
 * -----
 *
 * @example (body parameter with schema reference):
 * ```ts
 * const bodyParam: BodyParameter = {
 *   name: "user",
 *   in: "body",
 *   description: "User object to create",
 *   required: true,
 *   schema: { $ref: "#/definitions/User" }
 * };
 * ```
 *
 * @example (body parameter with inline schema):
 * ```ts
 * const bodyParam: BodyParameter = {
 *   name: "data",
 *   in: "body",
 *   description: "Request data",
 *   required: true,
 *   schema: {
 *     type: "object",
 *     properties: {
 *       name: { type: "string" },
 *       age: { type: "integer" }
 *     }
 *   }
 * };
 * ```
 */
export interface BodyParameter extends Extension {
  /**
   * The name of the parameter. For body parameters, this is used for documentation
   * purposes only and has no effect on the parameter itself.
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - name}
   *
   * @example "user"
   * @example "data"
   * @example "payload"
   */
  name: string;

  /**
   * The location of the parameter. Must be "body" for body parameters.
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - in}
   *
   * @example "body"
   */
  in: "body";

  /**
   * A brief description of the parameter. This could contain examples of use.
   * GFM syntax can be used for rich text representation.
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - description}
   *
   * @example "User object to create"
   * @example "Request payload containing the data to process"
   */
  description?: string;

  /**
   * Determines whether this parameter is mandatory. Default value is false.
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - required}
   *
   * @default false
   * @example true
   */
  required?: boolean;

  /**
   * The schema defining the type used for the body parameter. This property is
   * required for body parameters.
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - schema}
   *
   * @example { $ref: "#/definitions/User" }
   * @example { type: "object", properties: { name: { type: "string" } } }
   */
  schema: Schema;
}

/**
 * -----
 * Parameter Object (Non-Body Parameter)
 * -----
 *
 * Describes a non-body parameter for an API operation. These parameters include
 * query, header, path, and formData parameters. They have different validation
 * rules and properties compared to body parameters.
 *
 * Non-body parameters support simple types (string, number, integer, boolean, array, file)
 * and include validation properties like format, pattern, minimum, maximum, etc.
 *
 * | Version | Reference |
 * |---|-----|
 * | 2.0     | {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Parameter Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `name` - The name of the parameter
 * @property `in` - The location of the parameter ("query", "header", "path", "formData")
 * @property `description` - A brief description of the parameter
 * @property `required` - Whether the parameter is mandatory (required for path parameters)
 * @property `type` - The type of the parameter (required for non-body parameters)
 * @property `format` - The extending format for the type
 * @property `allowEmptyValue` - Whether empty values are allowed
 * @property `items` - Schema for array items (required if type is "array")
 * @property `collectionFormat` - Format for array parameters
 * @property `default` - Default value for the parameter
 * @property `maximum` - Maximum value for numbers
 * @property `exclusiveMaximum` - Whether maximum is exclusive
 * @property `minimum` - Minimum value for numbers
 * @property `exclusiveMinimum` - Whether minimum is exclusive
 * @property `maxLength` - Maximum length for strings
 * @property `minLength` - Minimum length for strings
 * @property `pattern` - Regular expression pattern for strings
 * @property `maxItems` - Maximum number of items in arrays
 * @property `minItems` - Minimum number of items in arrays
 * @property `uniqueItems` - Whether array items must be unique
 * @property `enum` - Array of valid values
 * @property `multipleOf` - Value must be a multiple of this number
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * Path parameters are always required. The type property is required for
 * non-body parameters. File type is only valid for formData parameters.
 *
 * -----
 * Examples
 * -----
 *
 * @example (query parameter):
 * ```ts
 * const queryParam: NonBodyParameter = {
 *   name: "limit",
 *   in: "query",
 *   description: "Maximum number of items to return",
 *   required: false,
 *   type: "integer",
 *   format: "int32",
 *   default: 10
 * };
 * ```
 *
 * @example (path parameter):
 * ```ts
 * const pathParam: NonBodyParameter = {
 *   name: "id",
 *   in: "path",
 *   description: "User ID",
 *   required: true,
 *   type: "string"
 * };
 * ```
 *
 * @example (header parameter):
 * ```ts
 * const headerParam: NonBodyParameter = {
 *   name: "X-API-Key",
 *   in: "header",
 *   description: "API key for authentication",
 *   required: true,
 *   type: "string"
 * };
 * ```
 *
 * @example (form data parameter):
 * ```ts
 * const formParam: NonBodyParameter = {
 *   name: "file",
 *   in: "formData",
 *   description: "File to upload",
 *   required: true,
 *   type: "file"
 * };
 * ```
 */
export interface NonBodyParameter extends Extension {
  /**
   * The name of the parameter. Parameter names are case sensitive.
   * - If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object
   * - For all other cases, the name corresponds to the parameter name used by the in property
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - name}
   *
   * @example "id"
   * @example "limit"
   * @example "user"
   */
  name: string;

  /**
   * The location of the parameter. Possible values are "query", "header", "path", or "formData".
   *
   * - **query**: Parameters that are appended to the URL. For example, in `/users?role=admin`, the role query parameter has the value admin.
   * - **header**: Custom headers that are expected as part of the request. Note that RFC7230 states header names are case insensitive.
   * - **path**: Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API.
   * - **formData**: Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded or multipart/form-data is used as the content type of the request.
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - in}
   *
   * @example "query"
   * @example "path"
   * @example "header"
   * @example "formData"
   */
  in: "query" | "header" | "path" | "formData";

  /**
   * A brief description of the parameter. This could contain examples of use.
   * GFM syntax can be used for rich text representation.
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - description}
   *
   * @example "The user ID"
   * @example "Maximum number of items to return (default: 10)"
   */
  description?: string;

  /**
   * Determines whether this parameter is mandatory. If the parameter is in "path",
   * this property is required and its value MUST be true. Otherwise, the property
   * MAY be included and its default value is false.
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - required}
   *
   * @default false
   * @example true
   */
  required?: boolean;

  /**
   * The type of the parameter. Since the parameter is not located at the request body,
   * it is limited to simple types (that is, not an object). The value MUST be one of
   * "string", "number", "integer", "boolean", "array" or "file". If type is "file",
   * the consumes MUST be either "multipart/form-data", "application/x-www-form-urlencoded"
   * or both and the parameter MUST be in "formData".
   *
   * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - type}
   *
   * @example "string"
   * @example "integer"
   * @example "array"
   * @example "file"
   */
  type: "string" | "number" | "integer" | "boolean" | "array" | "file";

  /**
   * The extending format for the previously mentioned type. See Data Type Formats
   * for further details.
   *
   * @example "int32"
   * @example "date"
   * @example "email"
   */
  format?: string;

  /**
   * Sets the ability to pass empty-valued parameters. This is valid only for either
   * query or formData parameters and allows you to send a parameter with a name only
   * or an empty value. Default value is false.
   *
   * @default false
   * @example true
   */
  allowEmptyValue?: boolean;

  /**
   * Required if type is "array". Describes the type of items in the array.
   *
   * @example { type: "string" }
   * @example { type: "integer", format: "int32" }
   */
  items?: Items;

  /**
   * Determines the format of the array if type array is used. Possible values are:
   * - csv: comma separated values foo,bar
   * - ssv: space separated values foo bar
   * - tsv: tab separated values foo\tbar
   * - pipes: pipe separated values foo|bar
   * - multi: corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz
   *
   * @default "csv"
   * @example "multi"
   */
  collectionFormat?: "csv" | "ssv" | "tsv" | "pipes" | "multi";

  /**
   * Declares the value of the parameter that the server will use if none is provided.
   * This value MUST conform to the defined type for this parameter.
   *
   * @example "defaultValue"
   * @example 10
   */
  default?: unknown;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
   *
   * @example 100
   */
  maximum?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
   *
   * @example false
   */
  exclusiveMaximum?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
   *
   * @example 0
   */
  minimum?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
   *
   * @example false
   */
  exclusiveMinimum?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1
   *
   * @example 100
   */
  maxLength?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2
   *
   * @example 1
   */
  minLength?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3
   *
   * @example "^[a-zA-Z0-9]+$"
   */
  pattern?: string;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2
   *
   * @example 10
   */
  maxItems?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3
   *
   * @example 1
   */
  minItems?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4
   *
   * @example true
   */
  uniqueItems?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1
   *
   * @example ["option1", "option2", "option3"]
   */
  enum?: unknown[];

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1
   *
   * @example 2
   */
  multipleOf?: number;
}

/**
 * Paths Object
 *
 * Holds the relative paths to the individual endpoints. The path is appended to the
 * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints.
 *
 * @see https://swagger.io/specification/v2/#paths-object
 * @example
 * ```typescript
 * const paths: Paths = {
 *   "/pets": {
 *     "get": {
 *       "description": "Returns all pets from the system that the user has access to",
 *       "produces": ["application/json"],
 *       "responses": {
 *         "200": {
 *           "description": "A list of pets.",
 *           "schema": {
 *             "type": "array",
 *             "items": {
 *               "$ref": "#/definitions/pet"
 *             }
 *           }
 *         }
 *       }
 *     }
 *   }
 * }
 * ```
 */
export type Paths = Record<string, PathItem>;

/**
 * Items Object
 *
 * A limited subset of JSON-Schema's items object. It is used by parameter definitions
 * that are not located in "body".
 *
 * @see https://swagger.io/specification/v2/#items-object
 * @example
 * ```typescript
 * const items: Items = {
 *   type: "string",
 *   minLength: 2
 * }
 * ```
 */
export interface Items extends Extension {
  /**
   * The internal type of the array. The value MUST be one of "string", "number",
   * "integer", "boolean", or "array". Files and models are not allowed.
   *
   * @example "string"
   * @example "integer"
   * @example "array"
   */
  type: string;

  /**
   * The extending format for the previously mentioned type. See Data Type Formats
   * for further details.
   *
   * @example "int32"
   * @example "date"
   * @example "email"
   */
  format?: string;

  /**
   * Required if type is "array". Describes the type of items in the array.
   *
   * @example { type: "string" }
   * @example { type: "integer", format: "int32" }
   */
  items?: Items;

  /**
   * Determines the format of the array if type array is used. Possible values are:
   * - csv: comma separated values foo,bar
   * - ssv: space separated values foo bar
   * - tsv: tab separated values foo\tbar
   * - pipes: pipe separated values foo|bar
   *
   * @default "csv"
   * @example "multi"
   */
  collectionFormat?: "csv" | "ssv" | "tsv" | "pipes";

  /**
   * Declares the value of the item that the server will use if none is provided.
   * This value MUST conform to the defined type for the data type.
   *
   * @example "defaultValue"
   * @example 10
   */
  default?: unknown;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
   *
   * @example 100
   */
  maximum?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
   *
   * @example false
   */
  exclusiveMaximum?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
   *
   * @example 0
   */
  minimum?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
   *
   * @example false
   */
  exclusiveMinimum?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1
   *
   * @example 100
   */
  maxLength?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2
   *
   * @example 1
   */
  minLength?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3
   *
   * @example "^[a-zA-Z0-9]+$"
   */
  pattern?: string;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2
   *
   * @example 10
   */
  maxItems?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3
   *
   * @example 1
   */
  minItems?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4
   *
   * @example true
   */
  uniqueItems?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1
   *
   * @example ["option1", "option2", "option3"]
   */
  enum?: unknown[];

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1
   *
   * @example 2
   */
  multipleOf?: number;
}

/**
 * Paths Object
 *
 * Holds the relative paths to the individual endpoints. The path is appended to the
 * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints.
 *
 * @see https://swagger.io/specification/v2/#paths-object
 * @example
 * ```typescript
 * const paths: Paths = {
 *   "/pets": {
 *     "get": {
 *       "description": "Returns all pets from the system that the user has access to",
 *       "produces": ["application/json"],
 *       "responses": {
 *         "200": {
 *           "description": "A list of pets.",
 *           "schema": {
 *             "type": "array",
 *             "items": {
 *               "$ref": "#/definitions/pet"
 *             }
 *           }
 *         }
 *       }
 *     }
 *   }
 * }
 * ```
 */

/**
 * Response Object
 *
 * Describes a single response from an API Operation. A container for the expected
 * responses of an operation. The container maps a HTTP response code to the expected
 * response. It is not expected from the documentation to necessarily cover all
 * possible HTTP response codes because they may not be known in advance. However,
 * it is expected from the documentation to cover a successful operation response
 * and any known errors.
 *
 * @see https://swagger.io/specification/v2/#response-object
 * @example
 * ```typescript
 * const response: Response = {
 *   description: "User successfully retrieved",
 *   schema: { $ref: "#/definitions/User" },
 *   headers: {
 *     "X-RateLimit-Limit": {
 *       type: "integer",
 *       description: "Rate limit for the current period"
 *     }
 *   },
 *   examples: {
 *     "application/json": {
 *       id: 1,
 *       name: "John Doe",
 *       email: "john@example.com"
 *     }
 *   }
 * }
 * ```
 */
export interface Response extends Extension {
  /**
   * A short description of the response.
   * GitHub Flavored Markdown syntax can be used for rich text representation.
   *
   * See [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) for more information about the syntax.
   * This field is required.
   *
   * @example "User successfully retrieved"
   * @example "Bad request - invalid input parameters"
   * @example "Internal server error"
   */
  description: string;

  /**
   * A definition of the response structure. It can be a primitive, an array or an object.
   * If this field does not exist, it means no content is returned as part of the response.
   * As an extension to the Schema Object, its root type value may also be "file".
   * This SHOULD be accompanied by a relevant produces mime-type.
   *
   * @example { $ref: "#/definitions/User" }
   * @example { type: "array", items: { $ref: "#/definitions/User" } }
   * @example { type: "string" }
   */
  schema?: Schema;

  /**
   * A list of headers that are sent with the response.
   *
   * @example { "X-RateLimit-Limit": { type: "integer", description: "Rate limit" } }
   */
  headers?: Record<string, Header>;

  /**
   * An example of the response message.
   *
   * @example { "application/json": { id: 1, name: "John Doe" } }
   */
  examples?: Examples;
}

/**
 * Header Object
 *
 * Describes a single header parameter. A list of all headers that are sent with
 * the response. The name is used to refer to the respective header definition.
 * The value of the header is of type string.
 *
 * @see https://swagger.io/specification/v2/#header-object
 * @example
 * ```typescript
 * const header: Header = {
 *   description: "Rate limit for the current period",
 *   type: "integer",
 *   format: "int32"
 * }
 * ```
 */
export interface Header extends Extension {
  /**
   * A brief description of the header. GFM syntax can be used for rich text representation.
   *
   * @example "Rate limit for the current period"
   * @example "Content type of the response"
   */
  description?: string;

  /**
   * The type of the object. The value MUST be one of "string", "number", "integer",
   * "boolean", or "array".
   * This field is required.
   *
   * @example "string"
   * @example "integer"
   * @example "array"
   */
  type: string;

  /**
   * The extending format for the previously mentioned type. See Data Type Formats
   * for further details.
   *
   * @example "int32"
   * @example "date"
   * @example "email"
   */
  format?: string;

  /**
   * Required if type is "array". Describes the type of items in the array.
   *
   * @example { type: "string" }
   * @example { type: "integer", format: "int32" }
   */
  items?: Items;

  /**
   * Determines the format of the array if type array is used. Possible values are:
   * - csv: comma separated values foo,bar
   * - ssv: space separated values foo bar
   * - tsv: tab separated values foo\tbar
   * - pipes: pipe separated values foo|bar
   *
   * @default "csv"
   * @example "multi"
   */
  collectionFormat?: "csv" | "ssv" | "tsv" | "pipes";

  /**
   * Declares the value of the header that the server will use if none is provided.
   * This value MUST conform to the defined type for the header.
   *
   * @example "defaultValue"
   * @example 10
   */
  default?: unknown;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
   *
   * @example 100
   */
  maximum?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
   *
   * @example false
   */
  exclusiveMaximum?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
   *
   * @example 0
   */
  minimum?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
   *
   * @example false
   */
  exclusiveMinimum?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1
   *
   * @example 100
   */
  maxLength?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2
   *
   * @example 1
   */
  minLength?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3
   *
   * @example "^[a-zA-Z0-9]+$"
   */
  pattern?: string;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2
   *
   * @example 10
   */
  maxItems?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3
   *
   * @example 1
   */
  minItems?: number;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4
   *
   * @example true
   */
  uniqueItems?: boolean;

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1
   *
   * @example ["option1", "option2", "option3"]
   */
  enum?: unknown[];

  /**
   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1
   *
   * @example 2
   */
  multipleOf?: number;
}

export type Parameter = BodyParameter | NonBodyParameter;