Swagger AutoDoc

PowerShell Universal
1 
Product: PowerShell Universal
Version: 3.6.4

It looks like AutoDoc has been enabled in this version, and I can do the comment based output documentation. I’m struggling to see where I should put the component documentation… is there a new file, or does the component documentation mentioned in issue #1680 go in a separate file?

Specifically where does this code go:

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

I would like to get this working since I want to start using autorest to generate modules that can interact with my API endpoints.

2

We realized this problem too late, and we shouldn’t have “included” the feature in the 3.6 release. At least not announce that it was there. The ability to generate docs is enabled but there currently isn’t a place to put that information. In 3.7, we’re adding no-touch regions to PSU config files so that you can put whatever you want in them. The first iteration will allow you to create classes to define the request and response objects.

Endpoint config files will look like this.

#region PSUHeader 

# you can put whatever you want in here and you can still edit stuff in the admin console 

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

#endregion

New-PSUEndpoint -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 a very great return value.
            Content:
                application/json: MyReturnType

        400:
            Description: bad
}

The next iteration will have a nice UI for this directly alongside the API endpoints.

3

Ah, ok… so wait for 3.7 then!