Support for OpenAPI 3.x Callbacks

[mdaneri]

Feature

Add support for OpenAPI 3.x Callbacks

New Functions

• Add-PodeOACallBack
• New-PodeOAResponse
• Add-PodeOAComponentCallBack

Impacted Functions

• Add-PodeRoute

Parameters

Add-PodeOACallBack

• -Path
  Specifies the callback path, usually a relative URL.
  The key that identifies the Path Item Object is a runtime expression evaluated in the context of a runtime HTTP request/response to identify the URL for the callback request.
  A simple example is $request.body#/url.
  The runtime expression allows complete access to the HTTP message, including any part of a body that a JSON Pointer (RFC6901) can reference.
  More information on JSON Pointer can be found at RFC6901.

• -Name
  Alias for 'Name'. A unique identifier for the callback.
  It must be a valid string of alphanumeric characters, periods (.), hyphens (-), and underscores (_).

• -Reference
  A reference to a reusable CallBack component.

• -Method
  Defines the HTTP method for the callback (e.g., GET, POST, PUT). Supports standard HTTP methods and a wildcard (*) for all methods.

• -Parameters
  The Parameter definitions the request uses (from ConvertTo-PodeOAParameter).

• -RequestBody
  Defines the schema of the request body. Can be set using New-PodeOARequestBody.

• -Responses
  Defines the possible responses for the callback. Can be set using New-PodeOAResponse.

• -DefinitionTag
  An Array of strings representing the unique tag for the API specification.
  This tag helps in distinguishing 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.

Add-PodeOAComponentCallBack

• -Path
  Specifies the callback path, usually a relative URL.
  The key that identifies the Path Item Object is a runtime expression evaluated in the context of a runtime HTTP request/response to identify the URL for the callback request.
  A simple example is $request.body#/url.
  The runtime expression allows complete access to the HTTP message, including any part of a body that a JSON Pointer (RFC6901) can reference.
  More information on JSON Pointer can be found at RFC6901.

• -Name
  Alias for 'Name'. A unique identifier for the callback.
  It must be a valid string of alphanumeric characters, periods (.), hyphens (-), and underscores (_).

• -Method
  Defines the HTTP method for the callback (e.g., GET, POST, PUT). Supports standard HTTP methods and a wildcard (*) for all methods.

• -Parameters
  The Parameter definitions the request uses (from ConvertTo-PodeOAParameter).

• -RequestBody
  Defines the schema of the request body. Can be set using New-PodeOARequestBody.

• -Responses
  Defines the possible responses for the callback. Can be set using New-PodeOAResponse.

• -DefinitionTag
  An Array of strings representing the unique tag for the API specification.
  This tag helps in distinguishing 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.

Example

Add-PodeOACallBack

 Add-PodeRoute -PassThru -Method Post -Path '/petcallback'  -Authentication 'Login-OAuth2' -Scope 'write'  -ScriptBlock {
#code
            } | Set-PodeOARouteInfo -Summary 'Add a new pet to the store' -Description 'Add a new pet to the store' -Tags 'pet' -OperationId 'addPetcallback' -PassThru |
                Set-PodeOARequest -RequestBody (New-PodeOARequestBody -Reference 'PetBodySchema' ) -PassThru |
                Add-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content (New-PodeOAContentMediaType -MediaType 'application/json', 'application/xml' -Content 'Pet' ) -PassThru |
                Add-PodeOAResponse -StatusCode 405 -Description 'Validation exception' -Content @{
                    'application/json' = (New-PodeOAObjectProperty -Properties @(    (New-PodeOAStringProperty -Name 'result'), (New-PodeOAStringProperty -Name 'message')  ))
                } -PassThru |
                Add-PodeOACallBack -Name 'test' -Path '{$request.body#/id}' -Method Post  -RequestBody (New-PodeOARequestBody -Content @{'*/*' = (New-PodeOAStringProperty -Name 'id') } ) `
                    -Response (
                    New-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content (New-PodeOAContentMediaType -MediaType 'application/json', 'application/xml' -Content 'Pet' -Array) |
                        New-PodeOAResponse -StatusCode 400 -Description 'Invalid ID supplied' |
                        New-PodeOAResponse -StatusCode 404 -Description 'Pet not found' |
                        New-PodeOAResponse -Default   -Description 'Something is wrong'
                    )

Add-PodeOAComponentCallBack

Add-PodeOAComponentCallBack -Name 'test' -Path '{$request.body#/id}' -Method Post  -RequestBody (New-PodeOARequestBody -Content @{'*/*' = (New-PodeOAStringProperty -Name 'id') } ) `
                    -Response (
                    New-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content (New-PodeOAContentMediaType -MediaType 'application/json', 'application/xml' -Content 'Pet' -Array) |
                        New-PodeOAResponse -StatusCode 400 -Description 'Invalid ID supplied' |
                        New-PodeOAResponse -StatusCode 404 -Description 'Pet not found' |
                        New-PodeOAResponse -Default   -Description 'Something is wrong'
                    )

 Add-PodeRoute -PassThru -Method Post -Path '/petcallback'  -Authentication 'Login-OAuth2' -Scope 'write'  -ScriptBlock { 
#code
            } | Set-PodeOARouteInfo -Summary 'Add a new pet to the store' -Description 'Add a new pet to the store' -Tags 'pet' -OperationId 'addPetcallback' -PassThru |
                Set-PodeOARequest -RequestBody (New-PodeOARequestBody -Reference 'PetBodySchema' ) -PassThru |
                Add-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content (New-PodeOAContentMediaType -MediaType 'application/json', 'application/xml' -Content 'Pet' ) -PassThru |
                Add-PodeOAResponse -StatusCode 405 -Description 'Validation exception' -Content @{
                    'application/json' = (New-PodeOAObjectProperty -Properties @(    (New-PodeOAStringProperty -Name 'result'), (New-PodeOAStringProperty -Name 'message')  ))
                } -PassThru |
                Add-PodeOACallBack -Reference 'test'