Support for OpenAPI Schema validation Test

[mdaneri]

Describe the Feature

Implement a test to validate the parameters submitted by the clients with the OpenAPI specification.

Impacted Function

• -Enable-PodeOpenApi The switch parameter -EnableSchemaValidation is required to enable the feature

New Functions

• Test-PodeOAJsonSchemaCompliance

Parameters

• -Json The object in JSON format to validate

• -SchemaReference The schema name to use to validate the property.

• -Depth Specifies how many levels of the parameter objects are included in the JSON representation.

• -DefinitionTag A string representing the unique tag for the API specification. This tag helps distinguish between different versions or types of API specifications within the application. You can use this tag to reference the specific API documentation, schema, or version that your function interacts with.

Limitation

• The validation is possible for JSON only. For YAML, the content can be converted to JSON easily. For XML, the conversion is not straightforward.
• Schemas that include anyOff and oneOff cannot be tested due to a limitation of Powershell Test-Json
• Powershell version 6.x or greater is required
• Powershell Desktop 5.1 doesn't support this feature

Example

Enable-PodeOpenApi -Path '/docs/openapi' -OpenApiVersion '3.0.3' -EnableSchemaValidation -DisableMinimalDefinitions -NoDefaultResponses

Add-PodeRoute -PassThru -Method Put -Path '/pet' -Authentication 'merged_auth_nokey' -Scope 'write:pets', 'read:pets' -ScriptBlock {
            $contentType = Get-PodeHeader -Name 'Content-Type'
            switch ($contentType) {
                'application/xml' {
                    $pet = ConvertFrom-PodeXML -node $WebEvent.data | ConvertTo-Json
                }
                'application/json' { $pet = ConvertTo-Json $WebEvent.data }
                default {
                    Write-PodeHtmlResponse -StatusCode 415
                    return
                }
            }
            if ($pet -and $WebEvent.data.id) {
                if ($contentType -eq 'application/json') {
                    $Validate = Test-PodeOAJsonSchemaCompliance -Json $pet -SchemaReference 'Pet'
                } else {
                    $Validate = @{'result' = $true }
                }
                if ($Validate.result) {
                    if (Update-Pet -Pet (convertfrom-json -InputObject $pet -AsHashtable)) {
                        Save-PodeState -Path $using:PetDataJson
                    } else {
                        Write-PodeHtmlResponse -StatusCode 404 -Value  'Pet not found'
                    }
                } else {
                    Write-PodeHtmlResponse -StatusCode 405 -Value  ($Validate.message -join ', ')
                }
            } else {
                Write-PodeHtmlResponse -StatusCode 400 -Value 'Invalid ID supplied'
            }
        } | Set-PodeOARouteInfo -Summary 'Update an existing pet' -Description 'Update an existing pet by Id' -Tags 'pet' -OperationId 'updatePet' -PassThru |
            Set-PodeOARequest -RequestBody (
                New-PodeOARequestBody -Description  'Update an existent pet in the store' -Required -Content (
                    New-PodeOAContentMediaType -MediaType 'application/json', 'application/xml' -Content 'Pet'  )
            ) -PassThru |
            Add-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content (New-PodeOAContentMediaType -MediaType 'application/json', 'application/xml' -Content 'Pet' ) -PassThru |
            Add-PodeOAResponse -StatusCode 400 -Description 'Invalid ID supplied' -PassThru |
            Add-PodeOAResponse -StatusCode 404 -Description 'Pet not found' -PassThru |
            Add-PodeOAResponse -StatusCode 405 -Description 'Validation exception'