OpenAPI

Documentation standardisée pour vos points de terminaison.

À propos

La documentation de l'API peut être produite pour vos points de terminaison en créant une nouvelle définition OpenAPI et en y assignant des points de terminaison. OpenAPI est un format standard qui peut être utilisé par des outils tels que OpenAPI Generator ou Swagger Codegen pour créer des clients. Le tableau de bord Swagger est également intégré à PowerShell Universal afin de fournir une documentation interactive.

Documentation de l'API de gestion

Vous pouvez consulter la documentation de l'API de gestion en accédant au tableau de bord Swagger intégré.

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

Créer un document OpenAPI

Pour créer une définition OpenAPI, cliquez sur APIs \ Documentation, puis sur Create new Endpoint Documentation. Vous pouvez définir le nom, l'URL, la description et les détails d'authentification de la documentation.

Boîte de dialogue de documentation des points de terminaison

Une fois créée, vous pouvez assigner des points de terminaison à la documentation en modifiant le point de terminaison.

Modifier le point de terminaison

La documentation de votre point de terminaison apparaîtra dans le tableau de bord Swagger. Sélectionnez la définition à l'aide du menu déroulant Select a definition.

Tous vos points de terminaison personnalisés seront répertoriés.

Documentation Swagger pour les API

Texte d'aide

Vous pouvez spécifier du texte d'aide pour vos API à l'aide de l'aide basée sur les commentaires. L'inclusion d'un synopsis, d'une description et de descriptions de paramètres entraîne la documentation de chacun de ces éléments dans la documentation OpenAPI et dans la page Swagger.

Par exemple, avec un simple point de terminaison /get/:id, nous pourrions avoir une aide basée sur les commentaires telle que celle-ci.

<# 
.SYNOPSIS
This is an endpoint

.DESCRIPTION
This is a description

.PARAMETER ID
This is an ID.

#>
param($ID)
    
$Id

La page Swagger résultante affichera chacune de ces descriptions.

Types d'entrée et de sortie

Les types peuvent être définis dans un ScriptBlock de documentation de point de terminaison. Cliquez sur le bouton Edit Details dans l'enregistrement de documentation de l'API.

Éditeur de documentation des points de terminaison

Les API peuvent également être documentées à l'aide de types d'entrée et de sortie en créant une classe PowerShell et en y faisant référence dans votre aide basée sur les commentaires. PowerShell Universal tire parti des sections .INPUTS et .OUTPUTS pour spécifier les formats acceptés et définir les valeurs de retour des codes d'état.

Dans les sections .INPUTS et .OUTPUTS, vous définirez un bloc YAML pour fournir ces informations. Pour créer des types, utilisez l'éditeur de documentation des points de terminaison. Ce fichier est chargé lors de la lecture des documents OpenAPI. Ces informations sont stockées dans endpointsDocumentation.ps1.

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

Entrées

Les types d'entrée sont définis dans la section .INPUTS. Cette section est un bloc YAML qui définit si l'entrée est obligatoire, fournit une description et spécifie le type de contenu. Il s'agit d'un type de contenu suivi de la classe PowerShell que vous avez définie dans la documentation du point de terminaison.

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

Sorties

Les types de sortie sont similaires aux entrées, mais sont spécifiés sur les codes de retour ainsi que sur leur type de contenu et leur classe PowerShell. L'exemple ci-dessous retourne une classe ADAccountType lorsqu'un HTTP OK (200) est retourné par l'API. Un code 400 (Bad Request) ne retourne pas de données, mais fournit une description qui sera affichée dans la documentation de l'API.

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

400:
  Description: Invalid input
#>
param()