Endpoint Documentation - External Endpoint Content

PowerShell Universal
1 
Product: PowerShell Universal
Version: 3.8.12

It looks like the .INPUTS does not work if the content is not in the main .endpoints.ps1 script

For example

My documentation in the external file for the endpoint looks like this.

<#
.SYNOPSIS
todo
.DESCRIPTION
todo

.OUTPUTS
    200:
        Description: Successful
    400:
        Description: The user account is null or empty or failed to invoke the pending exit script

.INPUTS 
    Required: true
    Description: UserAccount to exit
    Content: 
        application/json: MyObject
#>

# Use POST data from the body in JSON format
$Body = $Body | ConvertFrom-Json

It order to get MyObject to show up in the Swagger docs I need to add it to the .endpoints.ps1 script. It does not work in the external ps1 file.

#region PSUHeader 
[Documentation()]
class MyObject{
    [string]
	$UserAccount

	[int] 
	$id
}
#endregion

Hope this makes sense.

2

Also, does anyone know how to display nested objects?

For instance, I want to show the following JSON

[
    {
        "Script": "ActiveDirectory\\New-Account.ps1",
        "JobNumber": 20059,
        "JobData": {
            "UserPrincipalName": "test.test@domain",
            "DisplayName": "Roosevelt, test",
            "Description": "",
            "ObjectGUID": "",
            "SamAccountName": "test",
            "NewUserAccountParams": {
                "PostalCode": "",
                "DisplayName": "Roosevelt, Test2",
                "Name": "itpr1test2",
                "City": "",
                "SurName": "Roosevelt"
            },
            "somekey": "somevalue"
        }
    }
]

[Documentation()]
class NewADAccountSuccess {
  [string] $ComputerLoginID
  [string] $GivenName
  [string] $MiddleName
  [string] $SurName
  [string] $PreferredName
  [string] $Department
  [string] $OfficePhone
  [string] $StreetAddress
  [string] $City
  [string] $PostalCode
  [string] $State
  [string] $UserPrincipalName
}

Also not having luck with types

image

[Documentation()]
class EditADGroups {
    [string] $UserAccount
	[string] $SNRITMNumber
	[string[]] $Groups
	[bool] $RequestType
}
3

Having a hard time reproducing this one. I defined both the types in my docs file and included the string and bool types.

image
image1003×810 28.8 KB

This is my swagger doc page.

image
image588×755 15.2 KB

I used your endpoint definition.


    <#
.SYNOPSIS
todo
.DESCRIPTION
todo

.OUTPUTS
    200:
        Description: Successful
    400:
        Description: The user account is null or empty or failed to invoke the pending exit script

.INPUTS 
    Required: true
    Description: UserAccount to exit
    Content: 
        application/json: MyObject
#>

    # Use POST data from the body in JSON format
    $Body = $Body | ConvertFrom-Json

Do note, I’m trying this on 3.9.2

4

image

TBH I didn’t know you were supposed to put the class documentation under endpointdocumentation.ps1 but its still not working on this version. Ill test on 3.9.2

5

@adam - do you know how to document a class that might have nested items for a Responses example?

image
image697×704 16.5 KB 

[
    {
        "JobData": {
            "UserPrincipalName": "test.test@domain",
            "ObjectGUID": "",
            "NewUser": {
                "City": "",
                "SurName": "Roosevelt"
            }
        }
    }
]
6

Let me play around with that. I tried with .INPUT but not output. It seems like it should behave the same way but maybe something is not quite right.

1 Like