> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/es/api/openapi.md).

# OpenAPI

Genere documentación OpenAPI para los endpoints de PowerShell Universal, añada ayuda basada en comentarios y defina los tipos de entrada y salida para el panel de Swagger.

## Acerca de

Se puede generar documentación de API para sus endpoints creando una nueva definición OpenAPI y asignándole endpoints. OpenAPI es un formato estándar y puede ser consumido por herramientas, como [OpenAPI Generator](https://openapi-generator.tech/) o [Swagger Codegen](https://swagger.io/tools/swagger-codegen/), para crear clientes. El panel de Swagger también está integrado en PowerShell Universal para ofrecer 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 OpenAPI, haga clic en **Build > APIs > Documentation** y, a continuación, en Create new Endpoint Documentation. Puede establecer el nombre, la URL, la descripción y los datos de autenticación de la documentación.

Una vez creada, puede asignar endpoints a la documentación editando el 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 mostrarán todos sus endpoints personalizados.

## Texto de ayuda

Puede especificar el texto de ayuda de sus API mediante la ayuda basada en comentarios. Si incluye una sinopsis, una descripción y descripciones de los parámetros, cada uno de esos elementos quedará documentado en la documentación de OpenAPI y en la age de Swagger.

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

```powershell
<# 
.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.

Las API 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 Endpoint Documentation. Este fichero se carga al leer los documentos OpenAPI. Esta información se almacena en `endpointsDocumentation.ps1`.

```powershell
[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.

```powershell
<#
  .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.

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

400:
  Description: Invalid input
#>
param()
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/powershell-universal/es/api/openapi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.