OpenAPI

Informazioni

La documentazione API può essere prodotta per i suoi endpoint creando una nuova definizione OpenAPI e assegnandole degli endpoint. OpenAPI è un formato standard e può essere utilizzato da strumenti, come OpenAPI Generator o Swagger Codegen, per creare client. La dashboard Swagger è inoltre integrata in PowerShell Universal per fornire una documentazione interattiva.

Documentazione dell'API di gestione

Può visualizzare la documentazione dell'API di gestione visitando la dashboard Swagger integrata.

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

Creare un documento OpenAPI

Per creare una definizione OpenAPI, clicchi su APIs \ Documentation e poi su Create new Endpoint Documentation. Può impostare il nome, l'URL, la descrizione e i dettagli di autenticazione per la documentazione.

Finestra di dialogo Endpoint Documentation

Una volta creata, può assegnare gli endpoint alla documentazione modificando l'endpoint.

Modificare l'endpoint

La documentazione del suo endpoint apparirà nella dashboard Swagger. Selezioni la definizione con il menu a discesa Select a definition.

Verranno elencati tutti i suoi endpoint personalizzati.

Swagger Documentation for APIs

Testo della guida

Può specificare il testo della guida per le sue API utilizzando l'aiuto basato sui commenti. L'inclusione di una sinossi, di una descrizione e delle descrizioni dei parametri farà sì che ognuno di questi elementi venga documentato nella documentazione OpenAPI e nella pagina Swagger.

Ad esempio, con un semplice endpoint /get/:id, potremmo avere un aiuto basato sui commenti come questo.

<# 
.SYNOPSIS
This is an endpoint

.DESCRIPTION
This is a description

.PARAMETER ID
This is an ID.

#>
param($ID)
    
$Id

La pagina Swagger risultante mostrerà ciascuna di queste descrizioni.

Tipi di input e output

I tipi possono essere definiti all'interno di uno ScriptBlock della documentazione dell'endpoint. Clicchi sul pulsante Edit Details nel record della documentazione API.

Editor della documentazione dell'endpoint

Le API possono anche essere documentate utilizzando tipi di input e output creando una classe PowerShell e facendovi riferimento nell'aiuto basato sui commenti. PowerShell Universal sfrutta le sezioni .INPUTS e .OUTPUTS per specificare i formati accettati e definire i valori di ritorno dei codici di stato.

All'interno di .INPUTS e .OUTPUTS, definirà un blocco YAML per fornire queste informazioni. Per creare i tipi, utilizzi l'editor Endpoint Documentation. Questo file viene caricato durante la lettura dei documenti OpenAPI. Queste informazioni sono memorizzate in endpointsDocumentation.ps1.

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

Input

I tipi di input sono definiti nella sezione .INPUTS. Questa sezione è un blocco YAML che definisce se l'input è obbligatorio, fornisce una descrizione e specifica il tipo di contenuto. Si tratta di un tipo di contenuto seguito dalla classe PowerShell che ha definito nella documentazione dell'endpoint.

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

Output

I tipi di output sono simili a quelli di input, ma vengono specificati sui codici di ritorno oltre che sul relativo tipo di contenuto e sulla classe PowerShell. L'esempio seguente restituisce una classe ADAccountType quando l'API restituisce un HTTP OK (200). Un 400 (Bad Request) non restituisce dati, ma fornisce una descrizione che verrà visualizzata nella documentazione API.

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

400:
  Description: Invalid input
#>
param()