OpenAPI

Acerca de

Se puede generar documentación de la API para sus endpoints creando una nueva definición de OpenAPI y asignándole endpoints. OpenAPI es un formato estándar y puede ser consumido por herramientas, como OpenAPI Generator o Swagger Codegen, para crear clientes. El panel de Swagger también está integrado en PowerShell Universal para proporcionar documentación interactiva.

Documentación de la API de gestión

Puede consultar la documentación de la API de gestión visitando el panel de Swagger integrado.

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

Crear un documento OpenAPI

Para crear una definición de OpenAPI, haga clic en APIs \ Documentation y luego en Create new Endpoint Documentation. Puede establecer el nombre, la URL, la descripción y los detalles de autenticación de la documentación.

Diálogo de documentación de endpoints

Una vez creada, puede asignar endpoints a la documentación editando el endpoint.

Editar endpoint

La documentación de su endpoint aparecerá en el panel de Swagger. Seleccione la definición con el menú desplegable Select a definition.

Se enumerarán todos sus endpoints personalizados.

Documentación de Swagger para las APIs

Texto de ayuda

Puede especificar texto de ayuda para sus APIs mediante la ayuda basada en comentarios. Incluir una sinopsis, una descripción y descripciones de parámetros hará que cada una de esas partes se documente en la documentación de OpenAPI y en la página de Swagger.

Por ejemplo, con un endpoint sencillo /get/:id, podríamos tener una ayuda basada en comentarios como esta.

<# 
.SYNOPSIS
This is an endpoint

.DESCRIPTION
This is a description

.PARAMETER ID
This is an ID.

#>
param($ID)
    
$Id

La página de Swagger resultante mostrará cada una de estas descripciones.

Tipos de entrada y salida

Los tipos se pueden definir dentro de un ScriptBlock de documentación de endpoint. Haga clic en el botón Edit Details del registro de documentación de la API.

Editor de documentación de endpoints

Las APIs también se pueden documentar mediante tipos de entrada y salida creando una clase de PowerShell y haciendo referencia a ella en su ayuda basada en comentarios. PowerShell Universal aprovecha las secciones .INPUTS y .OUTPUTS para especificar los formatos aceptados y definir los valores de retorno de los códigos de estado.

Dentro de .INPUTS y .OUTPUTS, definirá un bloque YAML para proporcionar esta información. Para crear tipos, utilice el editor de documentación de endpoints. Este fichero se carga al leer documentos OpenAPI. Esta información se almacena en endpointsDocumentation.ps1.

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

Entradas

Los tipos de entrada se definen en la sección .INPUTS. Esta sección es un bloque YAML que define si la entrada es obligatoria, proporciona una descripción y especifica el tipo de contenido. Se trata de un tipo de contenido seguido de la clase de PowerShell que definió en la documentación del endpoint.

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

Salidas

Los tipos de salida son similares a los de entrada, pero se especifican en los códigos de retorno, así como su tipo de contenido y su clase de PowerShell. El siguiente ejemplo devuelve una clase ADAccountType cuando la API devuelve un HTTP OK (200). Un 400 (Bad Request) no devuelve datos, pero sí proporciona una descripción que se mostrará en la documentación de la API.

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

400:
  Description: Invalid input
#>
param()