OpenApi Server Endpoint autoconfiguration improvement

[mdaneri]

Describe the Feature

In Pode, multiple ways exist to define an endpoint, but all of them are doing more than needed and are not easy to use.

In Pode usually the endpoint is the server itself, not an external one and normally the endpoint URL is going to overlap the initial path of almost any OpenAPI Path

For this reason, there is a new function that allow to definition any server endpoint and more specifically the local server endpoint

New Function

• -Add-PodeOAServerEndpoint

Parameters

• -Url A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.

• -Description An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.

• -Variables A map between a variable name and its value. The value is used for substitution in the server's URL template.

• -DefinitionTag An Array of strings 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. A clear and concise description of what the problem is, or a link/reference to the issue.

Example

Add-PodeOAServerEndpoint -url '/api/v3' -Description 'default endpoint'

Add-PodeRoute -PassThru -Method Get -Path '/api/v3/pet/:petId' -Authentication 'merged_auth' -Scope 'write:pets', 'read:pets' -ScriptBlock {
#code
 } | Set-PodeOARouteInfo -Summary 'Find pet by ID' -Description 'Returns a single pet.' -Tags 'pet' -OperationId 'getPetById' -PassThru | 
Set-PodeOARequest -PassThru -Parameters ( 
  New-PodeOAIntProperty -Name 'petId' -Description 'ID of pet to return'  -Format Int64 | 
  ConvertTo-PodeOAParameter -In Path -Required 
) | 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 415

openapi : 3.1.0
jsonSchemaDialect : https://spec.openapis.org/oas/3.1/dialect/base
servers : 
  - url : /api/v3
    description : default endpoint
paths : 
  /pet/{petId} : 
    get : 
      tags : 
        - pet
      summary : Find pet by ID
      description : Returns a single pet.
      operationId : getPetById
      parameters : 
        - schema : 
            type : integer
            format : int64
          description : ID of pet to return
          in : path
          required : true
          name : petId
      security : 
        - Basic : []
        - api_key : []
      responses : 
        400 : 
          description : Invalid ID supplied
        415 : 
          description : Unsupported Media Type
        404 : 
          description : Pet not found
        200 : 
          description : Successful operation
          content : 
            application/xml : 
              schema : 
                $ref : '#/components/schemas/Pet'
            application/json : 
              schema : 
                $ref : '#/components/schemas/Pet'