API Documentation Body Doc

PowerShell Universal
1 
Product: PowerShell Universal
Version: 4.1.x

How do i document the Post Body json? I cannot find any documentation on this:

image

2

I just checked and the documentation is outdated. You should be able to add classes to the documentation file like this.

[Documentation()]
class MyReturnType {
    [string]$Value
}

Then you would set it as the input type.

New-PSUEndpoint -Url "/documented" -Method @('GET') -Endpoint {
<# 
.SYNOPSIS
This is an endpoint
    
.DESCRIPTION
This is a description

.PARAMETER Id
This is an ID.

.PARAMETER AnotherOne
This is AnotherOne

.OUTPUTS
    200:
        Description: This is an output value. 
        Content:
            application/json: MyReturnType

    400:
        Description: Invalid input
.INPUTS 
    Required: false
    Description: This is an input value.
    Content: 
        application/json: MyReturnType

#>
param($Id, $AnotherOne)
} -Authentication

This is what I’m referring to.

.INPUTS 
    Required: false
    Description: This is an input value.
    Content: 
        application/json: MyReturnType

I’ll add something to my todo list to improve this example.

1 Like
3

How does this help someone that’s never used this product before?

I love the idea or promise of PSU and got my company to buy it but some days I highly regret it.

Why would I define classes for documentation? None of this makes any sense to me.

4

@tonesto7 What else would you suggest? I mean, if we’re talking about custom object definitions why would you not use classes?

1 Like
5

I think the difficulty here would be that using something like json or another “data” format wouldn’t allow defining the data type of the expected response properties. A PSCustomObject or hashtable wouldn’t allow defining the type either if the example value given was a null. Classes are really the only thing that can do this effectively and are a familiar architype to most. It doesn’t need to be anything complex, just the simplest definition.

P.S. I’m generally a proponent of functional programming and composition over inheritance, but the right tool for the job always trumps philosophical arguments.

2 Likes
6

@tonesto7, The underlying Swagger technology requires an input that is a class. Why would we make something to translate into a class and have another point of failure?

7

if you use [bool]$test then it only show null in the output , if you add [bool]$test = $false then it show it as string for the user.
It would be great if it did show it as json bool

Also it don’t seem possible to make it show nested objects either.

1 Like
8

Agreed. The current implementation doesn’t seem to allow you to effectively populate example values or custom type enums in the swagger docs. Hopefully more functionality can be added in a future release. Any planned work here, @adam ?