OpenAPI

About

API documentation can be produced for your endpoints by creating a new OpenAPI definition and assigning endpoints to it. OpenAPI is a standard format and can be consumed by tools, such as the OpenAPI Generator or Swagger Codegen, to create clients. The Swagger dashboard is also integrated into PowerShell Universal to provide interactive documentation.

Create an OpenAPI Document

To create an OpenAPI definition, click APIs \ Documentation and then Create new Endpoint Documentation. You can set the name, URL, description and authentication details for the documentation.

Once created, you can assign endpoints to the documentation by editing the endpoint.

The documentation for your endpoint will appear within the Swagger dashboard. Select the definition with the Select a definition dropdown.

All your custom endpoints will be listed.

Help Text

You can specify help text for your APIs using comment-based help. Including a synopsis, description and parameter descriptions will result in each of those pieces being documented in the OpenAPI documentation and Swagger age.

For example, with a simple /get/:id endpoint, we could have comment-based help such as this.

<# 
.SYNOPSIS
This is an endpoint

.DESCRIPTION
This is a description

.PARAMETER ID
This is an ID.

#>
param($ID)
    
$Id

The resulting Swagger page will show each of these descriptions.

Input and Output Types

Types can be defined within an endpoint documentation ScriptBlock. Click the Edit Details button on the API documentation record.

APIs can also be documented using input and output types by creating a PowerShell class and referencing it within your comment-based help. PowerShell Universal takes advantage of the .INPUTS and .OUTPUTS sections to specify accepted formats and define status code return values.

Within the .INPUTS and .OUTPUTS , you will define a YAML block to provide this information. To create types, use the Endpoint Documentation editor. This file is loaded when reading OpenAPI documents. This information is stored in endpointsDocumentation.ps1.

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

Inputs

Input types are defined in the .INPUTS section. This section is a YAML block that defines if the input is required, provides a description and specifies the content type. This is a content type followed by the PowerShell class you defined in the endpoint documentation.

<#
  .INPUTS
  Required: false
  Description: This is an input value.
  Content:
      application/json: MyReturnType 
#>
param()

Outputs

Output types are similar to input but are specified on return codes as well as their content type and PowerShell class. The below example returns an ADAccountType class when a HTTP OK (200) is returned from the API. A 400 (Bad Request) does not return data but does provide a description that will be displayed in the API documentation.

<#
.OUTPUTS
200:
  Description: This is an output value. 
  Content:
      application/json: ADAccountType

400:
  Description: Invalid input
#>
param()