Merge cf7d416 into efb6b3e

docs/Tutorials/OpenAPI.md

@@ -84,7 +84,7 @@ Each of the following OpenAPI functions have a `-PassThru` switch, allowing you
 
 ### Responses
 
-You can define multiple responses for a route, but only one of each status code, using the [`Add-PodeOAResponse`](../../Functions/OpenApi/Add-PodeOAResponse) function. You can either just define the response and status code; with a custom description; or with a schema defining the payload of the response.
+You can define multiple responses for a route, but only one of each status code, using the [`Add-PodeOAResponse`](../../Functions/OpenApi/Add-PodeOAResponse) function. You can either just define the response and status code, with a custom description, or with a schema defining the payload of the response.
 
 The following is an example of defining simple 200 and 404 responses on a route:
 
@@ -123,6 +123,15 @@ the JSON response payload defined is as follows:
 }
 ```
 
+Internally, each route is created with an empty default 200 and 500 response. You can remove these, or other added responses, by using [`Remove-PodeOAResponse`](../../Functions/OpenApi/Add-PodeOAResponse):
+
+```powershell
+Add-PodeRoute -Method Get -Path "/api/user/:userId" -ScriptBlock {
+    # logic
+} -PassThru |
+    Remove-PodeOAResponse -StatusCode 200
+```
+
 ### Requests
 
 #### Parameters
@@ -359,8 +368,8 @@ New-PodeOAIntProperty -Name 'userId'
 # a float number with a max value of 100
 New-PodeOANumberProperty -Name 'ratio' -Format Float -Maximum 100
 
-# a string with a default value
-New-PodeOAStringProperty -Name 'type' -Default 'admin'
+# a string with a default value, and enum of options
+New-PodeOAStringProperty -Name 'type' -Default 'admin' -Enum @('admin', 'user')
 
 # a boolean that's required
 New-PodeOABoolProperty -Name 'enabled' -Required
@@ -370,7 +379,7 @@ On their own, like above, the simple properties don't really do much. However, y
 
 ### Arrays
 
-There isn't a dedicated function to create an array property, instead there is an `-Array` swicth on each of the propery functions - both Object and the above simple properties.
+There isn't a dedicated function to create an array property, instead there is an `-Array` switch on each of the property functions - both Object and the above simple properties.
 
 If you supply the `-Array` switch to any of the above simple properties, this will define an array of that type - the `-Name` parameter can also be omitted if only a simple array if required.
 

docs/release-notes.md

@@ -1,5 +1,13 @@
 # Release Notes
 
+## v1.8.3
+
+```plain
+### Enhancements
+* #602: Adds a new `Remove-PodeOAResponse` function to allow removing of default responses
+* #603: Adds a new `-Enum` parameter onto the OpenAPI property functions
+```
+
 ## v1.8.2
 
 ```plain

examples/web-rest-openapi-simple.ps1

@@ -25,7 +25,7 @@ Start-PodeServer {
         Write-PodeJsonResponse -Value @{ Name = 'Rick'; UserId = $e.Parameters['userId'] }
     } -PassThru |
         Set-PodeOARequest -Parameters @(
-            (New-PodeOAIntProperty -Name 'userId' -Required | ConvertTo-PodeOAParameter -In Path)
+            (New-PodeOAIntProperty -Name 'userId' -Enum @(100,300,999) -Required | ConvertTo-PodeOAParameter -In Path)
         )
 
 

src/Pode.psd1

@@ -194,6 +194,7 @@
         'Enable-PodeOpenApi',
         'Get-PodeOpenApiDefinition',
         'Add-PodeOAResponse',
+        'Remove-PodeOAResponse',
         'Add-PodeOAComponentResponse',
         'Set-PodeOAAuth',
         'Set-PodeOAGlobalAuth',

src/Public/OpenApi.ps1

@@ -301,6 +301,69 @@ function Add-PodeOAResponse
     }
 }
 
+<#
+.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)) {
+            $r.OpenApi.Responses.Remove($code) | Out-Null
+        }
+    }
+
+    if ($PassThru) {
+        return $Route
+    }
+}
+
 <#
 .SYNOPSIS
 Adds a reusable component for responses.
@@ -731,6 +794,9 @@ 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.
 
@@ -779,6 +845,10 @@ function New-PodeOAIntProperty
         [string]
         $Description,
 
+        [Parameter()]
+        [int[]]
+        $Enum,
+
         [switch]
         $Required,
 
@@ -801,6 +871,7 @@ function New-PodeOAIntProperty
         deprecated = $Deprecated.IsPresent
         description = $Description
         format = $Format.ToLowerInvariant()
+        enum = $Enum
         default = $Default
     }
 
@@ -847,6 +918,9 @@ 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.
 
@@ -895,6 +969,10 @@ function New-PodeOANumberProperty
         [string]
         $Description,
 
+        [Parameter()]
+        [double[]]
+        $Enum,
+
         [switch]
         $Required,
 
@@ -917,6 +995,7 @@ function New-PodeOANumberProperty
         deprecated = $Deprecated.IsPresent
         description = $Description
         format = $Format.ToLowerInvariant()
+        enum = $Enum
         default = $Default
     }
 
@@ -966,6 +1045,9 @@ 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.
 
@@ -1021,6 +1103,10 @@ function New-PodeOAStringProperty
         [string]
         $Description,
 
+        [Parameter()]
+        [string[]]
+        $Enum,
+
         [switch]
         $Required,
 
@@ -1048,6 +1134,7 @@ function New-PodeOAStringProperty
         deprecated = $Deprecated.IsPresent
         description = $Description
         format = $_format.ToLowerInvariant()
+        enum = $Enum
         pattern = $Pattern
         default = $Default
     }
@@ -1079,6 +1166,9 @@ 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.
 
@@ -1110,6 +1200,10 @@ function New-PodeOABoolProperty
         [string]
         $Description,
 
+        [Parameter()]
+        [bool[]]
+        $Enum,
+
         [switch]
         $Required,
 
@@ -1131,6 +1225,7 @@ function New-PodeOABoolProperty
         required = $Required.IsPresent
         deprecated = $Deprecated.IsPresent
         description = $Description
+        enum = $Enum
         default = $Default
     }
 
@@ -1272,6 +1367,7 @@ function ConvertTo-PodeOAParameter
         schema = @{
             type = $Property.type
             format = $Property.format
+            enum = $Property.enum
         }
     }