| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Creates a new OpenAPI Component Example object. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | This cmdlet creates a new OpenAPI Component Example object that can be used in OpenAPI specifications. |
| | | 6 | | .PARAMETER Server |
| | | 7 | | The Kestrun server instance to use. If not specified, the default server instance is used. |
| | | 8 | | .PARAMETER Summary |
| | | 9 | | A short summary of what the example is about. |
| | | 10 | | .PARAMETER Description |
| | | 11 | | A verbose explanation of the example. |
| | | 12 | | .PARAMETER ExternalValue |
| | | 13 | | A URL that points to the literal example. |
| | | 14 | | .PARAMETER Value |
| | | 15 | | The actual example payload. Can be hashtable/pscustomobject/string/number/etc. |
| | | 16 | | .PARAMETER DataValue |
| | | 17 | | The actual example payload as an OpenAPI 3.2 native field. In OpenAPI 3.1, it serializes as x-oai-dataValue. |
| | | 18 | | .PARAMETER SerializedValue |
| | | 19 | | The serialized representation of the DataValue. In OpenAPI 3.1, it serializes as x-oai-serializedValue. |
| | | 20 | | .PARAMETER Extensions |
| | | 21 | | A dictionary of OpenAPI extensions to add to the example. |
| | | 22 | | .OUTPUTS |
| | | 23 | | Microsoft.OpenApi.OpenApiExample object. |
| | | 24 | | .EXAMPLE |
| | | 25 | | $example = New-KrOpenApiExample -Summary "User Example" -Description "An example of a user object." -Value @{ id = 1 |
| | | 26 | | This example creates a new OpenAPI Component Example with a summary, description, and a value. |
| | | 27 | | .EXAMPLE |
| | | 28 | | $example = New-KrOpenApiExample -Summary "External Example" -ExternalValue "http://example.com/example.json" |
| | | 29 | | This example creates a new OpenAPI Component Example that references an external example. |
| | | 30 | | .EXAMPLE |
| | | 31 | | $dataValue = @{ id = 2; name = "Jane Doe" } |
| | | 32 | | $example = New-KrOpenApiExample -Summary "Data Value Example" -DataValue $dataValue -SerializedValue '{"id":2,"name" |
| | | 33 | | This example creates a new OpenAPI Component Example using the DataValue and SerializedValue parameters. |
| | | 34 | | .EXAMPLE |
| | | 35 | | $dataValue = @{ id = 3; name = "Alice" } |
| | | 36 | | $example = New-KrOpenApiExample -Summary "Auto Serialized Value Example" -DataValue $dataValue |
| | | 37 | | This example creates a new OpenAPI Component Example using the DataValue parameter and automatically serializes it t |
| | | 38 | | .NOTES |
| | | 39 | | #> |
| | | 40 | | function New-KrOpenApiExample { |
| | | 41 | | [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')] |
| | | 42 | | [KestrunRuntimeApi('Definition')] |
| | | 43 | | [CmdletBinding(DefaultParameterSetName = 'Value')] |
| | | 44 | | [OutputType([Microsoft.OpenApi.OpenApiExample])] |
| | | 45 | | param( |
| | | 46 | | [Parameter(Mandatory = $false, ValueFromPipeline = $true)] |
| | | 47 | | [Kestrun.Hosting.KestrunHost]$Server, |
| | | 48 | | |
| | | 49 | | [Parameter(Mandatory = $true)] |
| | | 50 | | [string]$Summary, |
| | | 51 | | |
| | | 52 | | [Parameter()] |
| | | 53 | | [string]$Description, |
| | | 54 | | |
| | | 55 | | [Parameter(Mandatory = $true, ParameterSetName = 'ExternalValue')] |
| | | 56 | | [string]$ExternalValue, |
| | | 57 | | |
| | | 58 | | [Parameter(Mandatory = $true, ParameterSetName = 'Value')] |
| | | 59 | | [AllowNull()] |
| | | 60 | | [object] $Value, |
| | | 61 | | |
| | | 62 | | [Parameter(Mandatory = $true, ParameterSetName = 'DataValue')] |
| | | 63 | | [AllowNull()] |
| | | 64 | | [object] $DataValue, |
| | | 65 | | |
| | | 66 | | [Parameter(ParameterSetName = 'DataValue')] |
| | | 67 | | [string] $SerializedValue, |
| | | 68 | | |
| | | 69 | | [Parameter()] |
| | | 70 | | [System.Collections.IDictionary]$Extensions |
| | | 71 | | ) |
| | | 72 | | |
| | | 73 | | begin { |
| | | 74 | | # Ensure the server instance is resolved |
| | 0 | 75 | | $Server = Resolve-KestrunServer -Server $Server |
| | | 76 | | } |
| | | 77 | | process { |
| | | 78 | | # Create example for the specified OpenAPI document |
| | 0 | 79 | | if ($Server.OpenApiDocumentDescriptor.Count -gt 0 ) { |
| | 0 | 80 | | $docDescriptor = $Server.DefaultOpenApiDocumentDescriptor |
| | | 81 | | |
| | 0 | 82 | | $example = switch ($PSCmdlet.ParameterSetName) { |
| | | 83 | | 'Value' { |
| | 0 | 84 | | $docDescriptor.NewOpenApiExample( |
| | | 85 | | $Summary, |
| | | 86 | | $Description, |
| | | 87 | | $Value, |
| | | 88 | | $Extensions |
| | | 89 | | ) |
| | | 90 | | } |
| | | 91 | | 'DataValue' { |
| | 0 | 92 | | $docDescriptor.NewOpenApiExample( |
| | | 93 | | $Summary, |
| | | 94 | | $Description, |
| | | 95 | | $DataValue, |
| | | 96 | | $SerializedValue, |
| | | 97 | | $Extensions |
| | | 98 | | ) |
| | | 99 | | } |
| | | 100 | | 'ExternalValue' { |
| | 0 | 101 | | $docDescriptor.NewOpenApiExternalExample( |
| | | 102 | | $Summary, |
| | | 103 | | $Description, |
| | | 104 | | $ExternalValue, |
| | | 105 | | $Extensions |
| | | 106 | | ) |
| | | 107 | | } |
| | | 108 | | } |
| | | 109 | | |
| | 0 | 110 | | return $example |
| | | 111 | | } |
| | | 112 | | } |
| | | 113 | | } |