OpenAPI

Über

API-Dokumentation kann für Ihre Endpunkte erstellt werden, indem Sie eine neue OpenAPI-Definition erstellen und ihr Endpunkte zuweisen. OpenAPI ist ein Standardformat und kann von Werkzeugen wie dem OpenAPI Generator oder Swagger Codegen genutzt werden, um Clients zu erstellen. Das Swagger-Dashboard ist ebenfalls in PowerShell Universal integriert, um interaktive Dokumentation bereitzustellen.

Dokumentation der Management-API

Sie können die Dokumentation der Management-API einsehen, indem Sie das integrierte Swagger-Dashboard besuchen.

http://localhost:5000/swagger/index.html

Ein OpenAPI-Dokument erstellen

Um eine OpenAPI-Definition zu erstellen, klicken Sie auf APIs \ Documentation und dann auf Create new Endpoint Documentation. Sie können den Namen, die URL, die Beschreibung und die Authentifizierungsdetails für die Dokumentation festlegen.

Dialog für Endpunkt-Dokumentation

Nach der Erstellung können Sie der Dokumentation Endpunkte zuweisen, indem Sie den Endpunkt bearbeiten.

Endpunkt bearbeiten

Die Dokumentation für Ihren Endpunkt erscheint im Swagger-Dashboard. Wählen Sie die Definition über das Dropdown-Menü Select a definition aus.

Alle Ihre benutzerdefinierten Endpunkte werden aufgelistet.

Swagger Documentation for APIs

Hilfetext

Sie können Hilfetext für Ihre APIs mithilfe kommentarbasierter Hilfe angeben. Wenn Sie eine Übersicht, eine Beschreibung und Parameterbeschreibungen einschließen, werden all diese Bestandteile in der OpenAPI-Dokumentation und auf der Swagger-Seite dokumentiert.

Zum Beispiel könnten wir bei einem einfachen /get/:id-Endpunkt eine kommentarbasierte Hilfe wie diese haben.

<# 
.SYNOPSIS
This is an endpoint

.DESCRIPTION
This is a description

.PARAMETER ID
This is an ID.

#>
param($ID)
    
$Id

Die resultierende Swagger-Seite zeigt jede dieser Beschreibungen an.

Eingabe- und Ausgabetypen

Typen können innerhalb eines ScriptBlocks der Endpunkt-Dokumentation definiert werden. Klicken Sie auf die Schaltfläche Edit Details im API-Dokumentationsdatensatz.

Editor für Endpunkt-Dokumentation

APIs können auch mit Eingabe- und Ausgabetypen dokumentiert werden, indem Sie eine PowerShell-Klasse erstellen und in Ihrer kommentarbasierten Hilfe darauf verweisen. PowerShell Universal nutzt die Abschnitte .INPUTS und .OUTPUTS, um akzeptierte Formate anzugeben und Rückgabewerte für Statuscodes zu definieren.

Innerhalb von .INPUTS und .OUTPUTS definieren Sie einen YAML-Block, um diese Informationen bereitzustellen. Verwenden Sie zum Erstellen von Typen den Editor für Endpunkt-Dokumentation. Diese Datei wird beim Lesen von OpenAPI-Dokumenten geladen. Diese Informationen werden in endpointsDocumentation.ps1 gespeichert.

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

Eingaben

Eingabetypen werden im Abschnitt .INPUTS definiert. Dieser Abschnitt ist ein YAML-Block, der definiert, ob die Eingabe erforderlich ist, eine Beschreibung bereitstellt und den Content-Type angibt. Dies ist ein Content-Type, gefolgt von der PowerShell-Klasse, die Sie in der Endpunkt-Dokumentation definiert haben.

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

Ausgaben

Ausgabetypen sind den Eingaben ähnlich, werden jedoch für Rückgabecodes sowie deren Content-Type und PowerShell-Klasse angegeben. Das folgende Beispiel gibt eine ADAccountType-Klasse zurück, wenn die API ein HTTP OK (200) zurückgibt. Ein 400 (Bad Request) gibt keine Daten zurück, stellt aber eine Beschreibung bereit, die in der API-Dokumentation angezeigt wird.

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

400:
  Description: Invalid input
#>
param()