> 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
## 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](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 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.
## 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.
```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.
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`.
```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=&goal=
```
`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.