Public/OpenApi.ps1

<#
.SYNOPSIS
Enables the OpenAPI default route in Pode.
 
.DESCRIPTION
Enables the OpenAPI default route in Pode, as well as setting up details like Title and API Version.
 
.PARAMETER Path
An optional custom route path to access the OpenAPI definition. (Default: /openapi)
 
.PARAMETER Title
The Title of the API.
 
.PARAMETER Version
The Version of the API. (Default: 0.0.0)
 
.PARAMETER Description
A Description of the API.
 
.PARAMETER RouteFilter
An optional route filter for routes that should be included in the definition. (Default: /*)
 
.PARAMETER Middleware
Like normal Routes, an array of Middleware that will be applied to the route.
 
.PARAMETER RestrictRoutes
If supplied, only routes that are available on the Requests URI will be used to generate the OpenAPI definition.
 
.EXAMPLE
Enable-PodeOpenApi -Title 'My API' -Version '1.0.0' -RouteFilter '/api/*'
 
.EXAMPLE
Enable-PodeOpenApi -Title 'My API' -Version '1.0.0' -RouteFilter '/api/*' -RestrictRoutes
 
.EXAMPLE
Enable-PodeOpenApi -Path '/docs/openapi' -Title 'My API' -Version '1.0.0'
#>

function Enable-PodeOpenApi
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]
        $Path = '/openapi',

        [Parameter(Mandatory=$true)]
        [string]
        $Title,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]
        $Version = '0.0.0',

        [Parameter()]
        [string]
        $Description,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]
        $RouteFilter = '/*',

        [Parameter()]
        [object[]]
        $Middleware,

        [switch]
        $RestrictRoutes
    )

    # initialise openapi info
    $PodeContext.Server.OpenAPI.Title = $Title
    $PodeContext.Server.OpenAPI.Path = $Path

    $meta = @{
        Version = $Version
        Description = $Description
        RouteFilter = $RouteFilter
        RestrictRoutes = $RestrictRoutes
    }

    # add the OpenAPI route
    Add-PodeRoute -Method Get -Path $Path -ArgumentList $meta -Middleware $Middleware -ScriptBlock {
        param($meta)
        $strict = $meta.RestrictRoutes

        # generate the openapi definition
        $def = Get-PodeOpenApiDefinitionInternal `
            -Title $PodeContext.Server.OpenAPI.Title `
            -Version $meta.Version `
            -Description $meta.Description `
            -RouteFilter $meta.RouteFilter `
            -Protocol $WebEvent.Endpoint.Protocol `
            -Address $WebEvent.Endpoint.Address `
            -EndpointName $WebEvent.Endpoint.Name `
            -RestrictRoutes:$strict

        # write the openapi definition
        Write-PodeJsonResponse -Value $def -Depth 20
    }
}

<#
.SYNOPSIS
Gets the OpenAPI definition.
 
.DESCRIPTION
Gets the OpenAPI definition for custom use in routes, or other functions.
 
.PARAMETER Title
The Title of the API. (Default: the title supplied in Enable-PodeOpenApi)
 
.PARAMETER Version
The Version of the API. (Default: the version supplied in Enable-PodeOpenApi)
 
.PARAMETER Description
A Description of the API. (Default: the description supplied into Enable-PodeOpenApi)
 
.PARAMETER RouteFilter
An optional route filter for routes that should be included in the definition. (Default: /*)
 
.PARAMETER RestrictRoutes
If supplied, only routes that are available on the Requests URI will be used to generate the OpenAPI definition.
 
.EXAMPLE
$def = Get-PodeOpenApiDefinition -RouteFilter '/api/*'
#>

function Get-PodeOpenApiDefinition
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]
        $Title,

        [Parameter()]
        [string]
        $Version,

        [Parameter()]
        [string]
        $Description,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]
        $RouteFilter = '/*',

        [switch]
        $RestrictRoutes
    )

    $Title = Protect-PodeValue -Value $Title -Default $PodeContext.Server.OpenAPI.Title
    if ([string]::IsNullOrWhiteSpace($Title)) {
        throw "No Title supplied for OpenAPI definition"
    }

    $Version = Protect-PodeValue -Value $Version -Default $PodeContext.Server.OpenAPI.Version
    if ([string]::IsNullOrWhiteSpace($Version)) {
        throw "No Version supplied for OpenAPI definition"
    }

    $Description = Protect-PodeValue -Value $Description -Default $PodeContext.Server.OpenAPI.Description

    # generate the openapi definition
    return (Get-PodeOpenApiDefinitionInternal `
        -Title $Title `
        -Version $Version `
        -Description $Description `
        -RouteFilter $RouteFilter `
        -Protocol $WebEvent.Endpoint.Protocol `
        -Address $WebEvent.Endpoint.Address `
        -EndpointName $WebEvent.Endpoint.Name `
        -RestrictRoutes:$RestrictRoutes)
}

<#
.SYNOPSIS
Adds a response definition to the supplied route.
 
.DESCRIPTION
Adds a response definition to the supplied route.
 
.PARAMETER Route
The route to add the response definition, usually from -PassThru on Add-PodeRoute.
 
.PARAMETER StatusCode
The HTTP StatusCode for the response.
 
.PARAMETER ContentSchemas
The content-types and schema the response returns (the schema is created using the Property functions).
 
.PARAMETER HeaderSchemas
The header name and schema the response returns (the schema is created using the Property functions).
 
.PARAMETER Description
A Description of the response. (Default: the HTTP StatusCode description)
 
.PARAMETER Reference
A Reference Name of an existing component response to use.
 
.PARAMETER Default
If supplied, the response will be used as a default response - this overrides the StatusCode supplied.
 
.PARAMETER PassThru
If supplied, the route passed in will be returned for further chaining.
 
.EXAMPLE
Add-PodeRoute -PassThru | Add-PodeOAResponse -StatusCode 200 -ContentSchemas @{ 'application/json' = (New-PodeOAIntProperty -Name 'userId' -Object) }
 
.EXAMPLE
Add-PodeRoute -PassThru | Add-PodeOAResponse -StatusCode 200 -ContentSchemas @{ 'application/json' = 'UserIdSchema' }
 
.EXAMPLE
Add-PodeRoute -PassThru | Add-PodeOAResponse -StatusCode 200 -Reference 'OKResponse'
#>

function Add-PodeOAResponse
{
    [CmdletBinding(DefaultParameterSetName='Schema')]
    param(
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [ValidateNotNullOrEmpty()]
        [hashtable[]]
        $Route,

        [Parameter(Mandatory=$true)]
        [int]
        $StatusCode,

        [Parameter(ParameterSetName='Schema')]
        [hashtable]
        $ContentSchemas,

        [Parameter(ParameterSetName='Schema')]
        [hashtable]
        $HeaderSchemas,

        [Parameter(ParameterSetName='Schema')]
        [string]
        $Description = $null,

        [Parameter(Mandatory=$true, ParameterSetName='Reference')]
        [string]
        $Reference,

        [switch]
        $Default,

        [switch]
        $PassThru
    )

    # set a general description for the status code
    if (!$Default -and [string]::IsNullOrWhiteSpace($Description)) {
        $Description = Get-PodeStatusDescription -StatusCode $StatusCode
    }

    # override status code with default
    $code = "$($StatusCode)"
    if ($Default) {
        $code = 'default'
    }

    # schemas or component reference?
    switch ($PSCmdlet.ParameterSetName.ToLowerInvariant()) {
        'schema' {
            # build any content-type schemas
            $content = $null
            if ($null -ne $ContentSchemas) {
                $content = ($ContentSchemas | ConvertTo-PodeOAContentTypeSchema)
            }

            # build any header schemas
            $headers = $null
            if ($null -ne $HeaderSchemas) {
                $headers = ($HeaderSchemas | ConvertTo-PodeOAHeaderSchema)
            }
        }

        'reference' {
            if (!(Test-PodeOAComponentResponse -Name $Reference)) {
                throw "The OpenApi component response doesn't exist: $($Reference)"
            }
        }
    }

    # add the respones to the routes
    foreach ($r in @($Route)) {
        switch ($PSCmdlet.ParameterSetName.ToLowerInvariant()) {
            'schema' {
                $r.OpenApi.Responses[$code] = @{
                    description = $Description
                    content = $content
                    headers = $headers
                }
            }

            'reference' {
                $r.OpenApi.Responses[$code] = @{
                    '$ref' = "#/components/responses/$($Reference)"
                }
            }
        }
    }

    if ($PassThru) {
        return $Route
    }
}

<#
.SYNOPSIS
Remove a response definition from the supplied route.
 
.DESCRIPTION
Remove a response definition from the supplied route.
 
.PARAMETER Route
The route to remove the response definition, usually from -PassThru on Add-PodeRoute.
 
.PARAMETER StatusCode
The HTTP StatusCode for the response to remove.
 
.PARAMETER Default
If supplied, the response will be used as a default response - this overrides the StatusCode supplied.
 
.PARAMETER PassThru
If supplied, the route passed in will be returned for further chaining.
 
.EXAMPLE
Add-PodeRoute -PassThru | Remove-PodeOAResponse -StatusCode 200
 
.EXAMPLE
Add-PodeRoute -PassThru | Remove-PodeOAResponse -StatusCode 201 -Default
#>

function Remove-PodeOAResponse
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [ValidateNotNullOrEmpty()]
        [hashtable[]]
        $Route,

        [Parameter(Mandatory=$true)]
        [int]
        $StatusCode,

        [switch]
        $Default,

        [switch]
        $PassThru
    )

    # override status code with default
    $code = "$($StatusCode)"
    if ($Default) {
        $code = 'default'
    }

    # remove the respones from the routes
    foreach ($r in @($Route)) {
        if ($r.OpenApi.Responses.ContainsKey($code)) {
            $null = $r.OpenApi.Responses.Remove($code)
        }
    }

    if ($PassThru) {
        return $Route
    }
}

<#
.SYNOPSIS
Adds a reusable component for responses.
 
.DESCRIPTION
Adds a reusable component for responses.
 
.PARAMETER Name
The reference Name of the response.
 
.PARAMETER ContentSchemas
The content-types and schema the response returns (the schema is created using the Property functions).
 
.PARAMETER HeaderSchemas
The header name and schema the response returns (the schema is created using the Property functions).
 
.PARAMETER Description
The Description of the response.
 
.EXAMPLE
Add-PodeOAComponentResponse -Name 'OKResponse' -ContentSchemas @{ 'application/json' = (New-PodeOAIntProperty -Name 'userId' -Object) }
 
.EXAMPLE
Add-PodeOAComponentResponse -Name 'ErrorResponse' -ContentSchemas @{ 'application/json' = 'ErrorSchema' }
#>

function Add-PodeOAComponentResponse
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]
        $Name,

        [Parameter()]
        [hashtable]
        $ContentSchemas,

        [Parameter()]
        [hashtable]
        $HeaderSchemas,

        [Parameter(Mandatory=$true)]
        [string]
        $Description
    )

    $content = $null
    if ($null -ne $ContentSchemas) {
        $content = ($ContentSchemas | ConvertTo-PodeOAContentTypeSchema)
    }

    $headers = $null
    if ($null -ne $HeaderSchemas) {
        $headers = ($HeaderSchemas | ConvertTo-PodeOAHeaderSchema)
    }

    $PodeContext.Server.OpenAPI.components.responses[$Name] = @{
        description = $Description
        content = $content
        headers = $headers
    }
}

<#
.SYNOPSIS
Sets the definition of a request for a route.
 
.DESCRIPTION
Sets the definition of a request for a route.
 
.PARAMETER Route
The route to set a request definition, usually from -PassThru on Add-PodeRoute.
 
.PARAMETER Parameters
The Parameter definitions the request uses (from ConvertTo-PodeOAParameter).
 
.PARAMETER RequestBody
The Request Body definition the request uses (from New-PodeOARequestBody).
 
.PARAMETER PassThru
If supplied, the route passed in will be returned for further chaining.
 
.EXAMPLE
Add-PodeRoute -PassThru | Set-PodeOARequest -RequestBody (New-PodeOARequestBody -Reference 'UserIdBody')
#>

function Set-PodeOARequest
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [ValidateNotNullOrEmpty()]
        [hashtable[]]
        $Route,

        [Parameter()]
        [hashtable[]]
        $Parameters,

        [Parameter()]
        [hashtable]
        $RequestBody,

        [switch]
        $PassThru
    )

    foreach ($r in @($Route)) {
        if (($null -ne $Parameters) -and ($Parameters.Length -gt 0)) {
            $r.OpenApi.Parameters = @($Parameters)
        }

        if ($null -ne $RequestBody) {
            $r.OpenApi.RequestBody = $RequestBody
        }
    }

    if ($PassThru) {
        return $Route
    }
}

<#
.SYNOPSIS
Creates a Request Body definition for routes.
 
.DESCRIPTION
Creates a Request Body definition for routes from the supplied content-types and schemas.
 
.PARAMETER Reference
A reference name from an existing component request body.
 
.PARAMETER ContentSchemas
The content-types and schema the request body accepts (the schema is created using the Property functions).
 
.PARAMETER Description
A Description of the request body.
 
.PARAMETER Required
If supplied, the request body will be flagged as required.
 
.EXAMPLE
New-PodeOARequestBody -ContentSchemas @{ 'application/json' = (New-PodeOAIntProperty -Name 'userId' -Object) }
 
.EXAMPLE
New-PodeOARequestBody -ContentSchemas @{ 'application/json' = 'UserIdSchema' }
 
.EXAMPLE
New-PodeOARequestBody -Reference 'UserIdBody'
#>

function New-PodeOARequestBody
{
    [CmdletBinding(DefaultParameterSetName='Schema')]
    param(
        [Parameter(Mandatory=$true, ParameterSetName='Reference')]
        [string]
        $Reference,

        [Parameter(Mandatory=$true, ParameterSetName='Schema')]
        [hashtable]
        $ContentSchemas,

        [Parameter(ParameterSetName='Schema')]
        [string]
        $Description = $null,

        [Parameter(ParameterSetName='Schema')]
        [switch]
        $Required
    )

    switch ($PSCmdlet.ParameterSetName.ToLowerInvariant()) {
        'schema' {
            return @{
                required = $Required.IsPresent
                description = $Description
                content = ($ContentSchemas | ConvertTo-PodeOAContentTypeSchema)
            }
        }

        'reference' {
            if (!(Test-PodeOAComponentRequestBody -Name $Reference)) {
                throw "The OpenApi component request body doesn't exist: $($Reference)"
            }

            return @{
                '$ref' = "#/components/requestBodies/$($Reference)"
            }
        }
    }
}

<#
.SYNOPSIS
Adds a reusable component for a request body.
 
.DESCRIPTION
Adds a reusable component for a request body.
 
.PARAMETER Name
The reference Name of the schema.
 
.PARAMETER Schema
The Schema definition (the schema is created using the Property functions).
 
.EXAMPLE
Add-PodeOAComponentSchema -Name 'UserIdSchema' -Schema (New-PodeOAIntProperty -Name 'userId' -Object)
#>

function Add-PodeOAComponentSchema
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]
        $Name,

        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [hashtable]
        $Schema
    )

    $PodeContext.Server.OpenAPI.components.schemas[$Name] = ($Schema | ConvertTo-PodeOASchemaProperty)
}

<#
.SYNOPSIS
Adds a reusable component for a request body.
 
.DESCRIPTION
Adds a reusable component for a request body.
 
.PARAMETER Name
The reference Name of the request body.
 
.PARAMETER ContentSchemas
The content-types and schema the request body accepts (the schema is created using the Property functions).
 
.PARAMETER Description
A Description of the request body.
 
.PARAMETER Required
If supplied, the request body will be flagged as required.
 
.EXAMPLE
Add-PodeOAComponentRequestBody -Name 'UserIdBody' -ContentSchemas @{ 'application/json' = (New-PodeOAIntProperty -Name 'userId' -Object) }
 
.EXAMPLE
Add-PodeOAComponentRequestBody -Name 'UserIdBody' -ContentSchemas @{ 'application/json' = 'UserIdSchema' }
#>

function Add-PodeOAComponentRequestBody
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]
        $Name,

        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [hashtable]
        $ContentSchemas,

        [Parameter()]
        [string]
        $Description = $null,

        [Parameter()]
        [switch]
        $Required
    )

    $PodeContext.Server.OpenAPI.components.requestBodies[$Name] = @{
        required = $Required.IsPresent
        description = $Description
        content = ($ContentSchemas | ConvertTo-PodeOAContentTypeSchema)
    }
}

<#
.SYNOPSIS
Adds a reusable component for a request parameter.
 
.DESCRIPTION
Adds a reusable component for a request parameter.
 
.PARAMETER Name
The reference Name of the parameter.
 
.PARAMETER Parameter
The Parameter to use for the component (from ConvertTo-PodeOAParameter)
 
.EXAMPLE
New-PodeOAIntProperty -Name 'userId' | ConvertTo-PodeOAParameter -In Query | Add-PodeOAComponentParameter -Name 'UserIdParam'
#>

function Add-PodeOAComponentParameter
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]
        $Name,

        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [hashtable]
        $Parameter
    )

    if ([string]::IsNullOrWhiteSpace($Name)) {
        $Name = $Parameter.name
    }

    $PodeContext.Server.OpenAPI.components.parameters[$Name] = $Parameter
}

<#
.SYNOPSIS
Creates a new OpenAPI integer property.
 
.DESCRIPTION
Creates a new OpenAPI integer property, for Schemas or Parameters.
 
.PARAMETER Name
The Name of the property.
 
.PARAMETER Format
The inbuilt OpenAPI Format of the integer. (Default: Any)
 
.PARAMETER Default
The default value of the property. (Default: 0)
 
.PARAMETER Minimum
The minimum value of the integer. (Default: Int.Min)
 
.PARAMETER Maximum
The maximum value of the integer. (Default: Int.Max)
 
.PARAMETER MultiplesOf
The integer must be in multiples of the supplied value.
 
.PARAMETER Description
A Description of the property.
 
.PARAMETER Enum
An optional array of values that this property can only be set to.
 
.PARAMETER Required
If supplied, the object will be treated as Required where supported.
 
.PARAMETER Deprecated
If supplied, the object will be treated as Deprecated where supported.
 
.PARAMETER Array
If supplied, the integer will be treated as an array of integers.
 
.PARAMETER Object
If supplied, the integer will be automatically wrapped in an object.
 
.EXAMPLE
New-PodeOANumberProperty -Name 'age' -Required
#>

function New-PodeOAIntProperty
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]
        $Name,

        [Parameter()]
        [ValidateSet('', 'Int32', 'Int64')]
        [string]
        $Format,

        [Parameter()]
        [int]
        $Default = 0,

        [Parameter()]
        [int]
        $Minimum = [int]::MinValue,

        [Parameter()]
        [int]
        $Maximum = [int]::MaxValue,

        [Parameter()]
        [int]
        $MultiplesOf = 0,

        [Parameter()]
        [string]
        $Description,

        [Parameter()]
        [int[]]
        $Enum,

        [switch]
        $Required,

        [switch]
        $Deprecated,

        [switch]
        $Array,

        [switch]
        $Object
    )

    $param = @{
        name = $Name
        type = 'integer'
        array = $Array.IsPresent
        object = $Object.IsPresent
        required = $Required.IsPresent
        deprecated = $Deprecated.IsPresent
        description = $Description
        format = $Format.ToLowerInvariant()
        default = $Default

        meta = @{
            enum = $Enum
        }
    }

    if ($Minimum -ne [int]::MinValue) {
        $param.meta['minimum'] = $Minimum
    }

    if ($Maximum -ne [int]::MaxValue) {
        $param.meta['maximum'] = $Maximum
    }

    if ($MultiplesOf -ne 0) {
        $param.meta['multipleOf'] = $MultiplesOf
    }

    return $param
}

<#
.SYNOPSIS
Creates a new OpenAPI number property.
 
.DESCRIPTION
Creates a new OpenAPI number property, for Schemas or Parameters.
 
.PARAMETER Name
The Name of the property.
 
.PARAMETER Format
The inbuilt OpenAPI Format of the number. (Default: Any)
 
.PARAMETER Default
The default value of the property. (Default: 0)
 
.PARAMETER Minimum
The minimum value of the number. (Default: Double.Min)
 
.PARAMETER Maximum
The maximum value of the number. (Default: Double.Max)
 
.PARAMETER MultiplesOf
The number must be in multiples of the supplied value.
 
.PARAMETER Description
A Description of the property.
 
.PARAMETER Enum
An optional array of values that this property can only be set to.
 
.PARAMETER Required
If supplied, the object will be treated as Required where supported.
 
.PARAMETER Deprecated
If supplied, the object will be treated as Deprecated where supported.
 
.PARAMETER Array
If supplied, the number will be treated as an array of numbers.
 
.PARAMETER Object
If supplied, the number will be automatically wrapped in an object.
 
.EXAMPLE
New-PodeOANumberProperty -Name 'gravity' -Default 9.8
#>

function New-PodeOANumberProperty
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]
        $Name,

        [Parameter()]
        [ValidateSet('', 'Double', 'Float')]
        [string]
        $Format,

        [Parameter()]
        [double]
        $Default = 0,

        [Parameter()]
        [double]
        $Minimum = [double]::MinValue,

        [Parameter()]
        [double]
        $Maximum = [double]::MaxValue,

        [Parameter()]
        [double]
        $MultiplesOf = 0,

        [Parameter()]
        [string]
        $Description,

        [Parameter()]
        [double[]]
        $Enum,

        [switch]
        $Required,

        [switch]
        $Deprecated,

        [switch]
        $Array,

        [switch]
        $Object
    )

    $param = @{
        name = $Name
        type = 'number'
        array = $Array.IsPresent
        object = $Object.IsPresent
        required = $Required.IsPresent
        deprecated = $Deprecated.IsPresent
        description = $Description
        format = $Format.ToLowerInvariant()
        default = $Default

        meta = @{
            enum = $Enum
        }
    }

    if ($Minimum -ne [double]::MinValue) {
        $param.meta['minimum'] = $Minimum
    }

    if ($Maximum -ne [double]::MaxValue) {
        $param.meta['maximum'] = $Maximum
    }

    if ($MultiplesOf -ne 0) {
        $param.meta['multipleOf'] = $MultiplesOf
    }

    return $param
}

<#
.SYNOPSIS
Creates a new OpenAPI string property.
 
.DESCRIPTION
Creates a new OpenAPI string property, for Schemas or Parameters.
 
.PARAMETER Name
The Name of the property.
 
.PARAMETER Format
The inbuilt OpenAPI Format of the string. (Default: Any)
 
.PARAMETER CustomFormat
The name of a custom OpenAPI Format of the string. (Default: None)
 
.PARAMETER Default
The default value of the property. (Default: $null)
 
.PARAMETER MinLength
The minimum length of the string. (Default: Int.Min)
 
.PARAMETER MaxLength
The maximum length of the string. (Default: Int.Max)
 
.PARAMETER Pattern
A Regex pattern that the string must match.
 
.PARAMETER Description
A Description of the property.
 
.PARAMETER Enum
An optional array of values that this property can only be set to.
 
.PARAMETER Required
If supplied, the object will be treated as Required where supported.
 
.PARAMETER Deprecated
If supplied, the object will be treated as Deprecated where supported.
 
.PARAMETER Array
If supplied, the string will be treated as an array of strings.
 
.PARAMETER Object
If supplied, the string will be automatically wrapped in an object.
 
.EXAMPLE
New-PodeOAStringProperty -Name 'userType' -Default 'admin'
 
.EXAMPLE
New-PodeOAStringProperty -Name 'password' -Format Password
#>

function New-PodeOAStringProperty
{
    [CmdletBinding(DefaultParameterSetName='Inbuilt')]
    param(
        [Parameter()]
        [string]
        $Name,

        [Parameter(ParameterSetName='Inbuilt')]
        [ValidateSet('', 'Binary', 'Byte', 'Date', 'Date-Time', 'Password')]
        [string]
        $Format,

        [Parameter(ParameterSetName='Custom')]
        [string]
        $CustomFormat,

        [Parameter()]
        [string]
        $Default = $null,

        [Parameter()]
        [int]
        $MinLength = [int]::MinValue,

        [Parameter()]
        [int]
        $MaxLength = [int]::MaxValue,

        [Parameter()]
        [string]
        $Pattern = $null,

        [Parameter()]
        [string]
        $Description,

        [Parameter()]
        [string[]]
        $Enum,

        [switch]
        $Required,

        [switch]
        $Deprecated,

        [switch]
        $Array,

        [switch]
        $Object
    )

    $_format = $Format
    if (![string]::IsNullOrWhiteSpace($CustomFormat)) {
        $_format = $CustomFormat
    }

    $param = @{
        name = $Name
        type = 'string'
        array = $Array.IsPresent
        object = $Object.IsPresent
        required = $Required.IsPresent
        deprecated = $Deprecated.IsPresent
        description = $Description
        format = $_format.ToLowerInvariant()
        default = $Default

        meta = @{
            enum = $Enum
            pattern = $Pattern
        }
    }

    if ($MinLength -ne [int]::MinValue) {
        $param.meta['minLength'] = $MinLength
    }

    if ($MaxLength -ne [int]::MaxValue) {
        $param.meta['maxLength'] = $MaxLength
    }

    return $param
}

<#
.SYNOPSIS
Creates a new OpenAPI boolean property.
 
.DESCRIPTION
Creates a new OpenAPI boolean property, for Schemas or Parameters.
 
.PARAMETER Name
The Name of the property.
 
.PARAMETER Default
The default value of the property. (Default: $false)
 
.PARAMETER Description
A Description of the property.
 
.PARAMETER Enum
An optional array of values that this property can only be set to.
 
.PARAMETER Required
If supplied, the object will be treated as Required where supported.
 
.PARAMETER Deprecated
If supplied, the object will be treated as Deprecated where supported.
 
.PARAMETER Array
If supplied, the boolean will be treated as an array of booleans.
 
.PARAMETER Object
If supplied, the boolean will be automatically wrapped in an object.
 
.EXAMPLE
New-PodeOABoolProperty -Name 'enabled' -Required
#>

function New-PodeOABoolProperty
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]
        $Name,

        [Parameter()]
        [bool]
        $Default = $false,

        [Parameter()]
        [string]
        $Description,

        [Parameter()]
        [bool[]]
        $Enum,

        [switch]
        $Required,

        [switch]
        $Deprecated,

        [switch]
        $Array,

        [switch]
        $Object
    )

    $param = @{
        name = $Name
        type = 'boolean'
        array = $Array.IsPresent
        object = $Object.IsPresent
        required = $Required.IsPresent
        deprecated = $Deprecated.IsPresent
        description = $Description
        default = $Default

        meta = @{
            enum = $Enum
        }
    }

    return $param
}

<#
.SYNOPSIS
Creates a new OpenAPI object property from other properties.
 
.DESCRIPTION
Creates a new OpenAPI object property from other properties, for Schemas or Parameters.
 
.PARAMETER Name
The Name of the property.
 
.PARAMETER Properties
An array of other int/string/etc properties wrap up as an object.
 
.PARAMETER Description
A Description of the property.
 
.PARAMETER Required
If supplied, the object will be treated as Required where supported.
 
.PARAMETER Deprecated
If supplied, the object will be treated as Deprecated where supported.
 
.PARAMETER Array
If supplied, the object will be treated as an array of objects.
 
.EXAMPLE
New-PodeOAObjectProperty -Name 'user' -Properties @('<ARRAY_OF_PROPERTIES>')
#>

function New-PodeOAObjectProperty
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]
        $Name,

        [Parameter(Mandatory=$true)]
        [hashtable[]]
        $Properties,

        [Parameter()]
        [string]
        $Description,

        [switch]
        $Required,

        [switch]
        $Deprecated,

        [switch]
        $Array
    )

    $param = @{
        name = $Name
        type = 'object'
        array = $Array.IsPresent
        required = $Required.IsPresent
        deprecated = $Deprecated.IsPresent
        description = $Description
        properties = $Properties
        default = $Default
    }

    return $param
}

<#
.SYNOPSIS
Creates a OpenAPI schema reference property.
 
.DESCRIPTION
Creates a new OpenAPI schema reference from another OpenAPI schema.
 
.PARAMETER Name
The Name of the property.
 
.PARAMETER Reference
An component schema name.
 
.PARAMETER Description
A Description of the property.
 
.PARAMETER Array
If supplied, the schema reference will be treated as an array.
 
.EXAMPLE
New-PodeOASchemaProperty -Name 'Config' -ComponentSchema "MyConfigSchema"
#>

function New-PodeOASchemaProperty
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]
        $Name,

        [Parameter(Mandatory=$true)]
        [string]
        $Reference,

        [Parameter()]
        [string]
        $Description,

        [switch]
        $Array
    )

    if(!(Test-PodeOAComponentSchema -Name $Reference)) {
        throw "The OpenApi component schema doesn't exist: $($Reference)"
    }

    $param = @{
        name = $Name
        type = 'schema'
        schema = $Reference
        array = $Array.IsPresent
        description = $Description
    }

    return $param
}

<#
.SYNOPSIS
Converts an OpenAPI property into a Request Parameter.
 
.DESCRIPTION
Converts an OpenAPI property (such as from New-PodeOAIntProperty) into a Request Parameter.
 
.PARAMETER In
Where in the Request can the parameter be found?
 
.PARAMETER Property
The Property that need converting (such as from New-PodeOAIntProperty).
 
.PARAMETER Reference
The name of an existing component parameter to be reused.
 
.EXAMPLE
New-PodeOAIntProperty -Name 'userId' | ConvertTo-PodeOAParameter -In Query
 
.EXAMPLE
ConvertTo-PodeOAParameter -Reference 'UserIdParam'
#>

function ConvertTo-PodeOAParameter
{
    [CmdletBinding(DefaultParameterSetName='Reference')]
    param(
        [Parameter(Mandatory=$true, ParameterSetName='Schema')]
        [ValidateSet('Cookie', 'Header', 'Path', 'Query')]
        [string]
        $In,

        [Parameter(Mandatory=$true, ValueFromPipeline=$true, ParameterSetName='Schema')]
        [ValidateNotNull()]
        [hashtable]
        $Property,

        [Parameter(Mandatory=$true, ParameterSetName='Reference')]
        [string]
        $Reference
    )

    # return a reference
    if ($PSCmdlet.ParameterSetName -ieq 'reference') {
        if (!(Test-PodeOAComponentParameter -Name $Reference)) {
            throw "The OpenApi component request parameter doesn't exist: $($Reference)"
        }

        return @{
            '$ref' = "#/components/parameters/$($Reference)"
        }
    }

    # non-object/array only
    if (@('array', 'object') -icontains $Property.type) {
        throw "OpenApi request parameter cannot be an array of object"
    }

    # build the base parameter
    $prop = @{
        in = $In.ToLowerInvariant()
        name = $Property.name
        description = $Property.description
        schema = @{
            type = $Property.type
            format = $Property.format
            enum = $Property.enum
        }
    }

    if ($Property.deprecated) {
        $prop['deprecated'] = $Property.deprecated
    }

    if ($Property.required) {
        $prop['required'] = $Property.required
    }

    # remove default for required parameter
    if (!$Property.required) {
        $prop.schema['default'] = $Property.default
    }

    return $prop
}

<#
.SYNOPSIS
Sets metadate for the supplied route.
 
.DESCRIPTION
Sets metadate for the supplied route, such as Summary and Tags.
 
.PARAMETER Route
The route to update info, usually from -PassThru on Add-PodeRoute.
 
.PARAMETER Summary
A quick Summary of the route.
 
.PARAMETER Description
A longer Description of the route.
 
.PARAMETER OperationId
Sets the OperationId of the route.
 
.PARAMETER Tags
An array of Tags for the route, mostly for grouping.
 
.PARAMETER Deprecated
If supplied, the route will be flagged as deprecated.
 
.PARAMETER PassThru
If supplied, the route passed in will be returned for further chaining.
 
.EXAMPLE
Add-PodeRoute -PassThru | Set-PodeOARouteInfo -Summary 'A quick summary' -Tags 'Admin'
#>

function Set-PodeOARouteInfo
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [ValidateNotNullOrEmpty()]
        [hashtable[]]
        $Route,

        [Parameter()]
        [string]
        $Summary,

        [Parameter()]
        [string]
        $Description,

        [Parameter()]
        [string]
        $OperationId,

        [Parameter()]
        [string[]]
        $Tags,

        [switch]
        $Deprecated,

        [switch]
        $PassThru
    )

    foreach ($r in @($Route)) {
        $r.OpenApi.Summary = $Summary
        $r.OpenApi.Description = $Description
        $r.OpenApi.OperationId = $OperationId
        $r.OpenApi.Tags = $Tags
        $r.OpenApi.Deprecated = $Deprecated.IsPresent
    }

    if ($PassThru) {
        return $Route
    }
}

<#
.SYNOPSIS
Adds a route that enables a viewer to display OpenAPI docs, such as Swagger or ReDoc.
 
.DESCRIPTION
Adds a route that enables a viewer to display OpenAPI docs, such as Swagger or ReDoc.
 
.PARAMETER Type
The Type of OpenAPI viewer to use.
 
.PARAMETER Path
The route Path where the docs can be accessed. (Default: "/$Type")
 
.PARAMETER OpenApiUrl
The URL where the OpenAPI definition can be retrieved. (Default is the OpenAPI path from Enable-PodeOpenApi)
 
.PARAMETER Middleware
Like normal Routes, an array of Middleware that will be applied.
 
.PARAMETER Title
The title of the web page.
 
.PARAMETER DarkMode
If supplied, the page will be rendered using a dark theme (this is not supported for all viewers).
 
.EXAMPLE
Enable-PodeOpenApiViewer -Type Swagger -DarkMode
 
.EXAMPLE
Enable-PodeOpenApiViewer -Type ReDoc -Title 'Some Title' -OpenApi 'http://some-url/openapi'
#>

function Enable-PodeOpenApiViewer
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [ValidateSet('Swagger', 'ReDoc')]
        [string]
        $Type,

        [Parameter()]
        [string]
        $Path,

        [Parameter()]
        [string]
        $OpenApiUrl,

        [Parameter()]
        [object[]]
        $Middleware,

        [Parameter()]
        [string]
        $Title,

        [switch]
        $DarkMode
    )

    # error if there's no OpenAPI URL
    $OpenApiUrl = Protect-PodeValue -Value $OpenApiUrl -Default $PodeContext.Server.OpenAPI.Path
    if ([string]::IsNullOrWhiteSpace($OpenApiUrl)) {
        throw "No OpenAPI URL supplied for $($Type)"
    }

    # fail if no title
    $Title = Protect-PodeValue -Value $Title -Default $PodeContext.Server.OpenAPI.Title
    $Title = Protect-PodeValue -Value $Title -Default $Type
    if ([string]::IsNullOrWhiteSpace($Title)) {
        throw "No title supplied for $($Type) page"
    }

    # set a default path
    $Path = Protect-PodeValue -Value $Path -Default "/$($Type.ToLowerInvariant())"
    if ([string]::IsNullOrWhiteSpace($Title)) {
        throw "No route path supplied for $($Type) page"
    }

    # setup meta info
    $meta = @{
        Type = $Type.ToLowerInvariant()
        Title = $Title
        OpenApi = $OpenApiUrl
        DarkMode = $DarkMode
    }

    # add the viewer route
    Add-PodeRoute -Method Get -Path $Path -Middleware $Middleware -ArgumentList $meta -ScriptBlock {
        param($meta)
        $podeRoot = Get-PodeModuleMiscPath
        Write-PodeFileResponse -Path ([System.IO.Path]::Combine($podeRoot, "default-$($meta.Type).html.pode")) -Data @{
            Title = $meta.Title
            OpenApi = $meta.OpenApi
            DarkMode = $meta.DarkMode
        }
    }
}