> 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/it/api/openapi.md).

# OpenAPI

Genera documentazione OpenAPI per gli endpoint di PowerShell Universal, aggiunge la guida basata su commenti e definisce i tipi di input e output per la dashboard Swagger.

## Informazioni

È possibile produrre documentazione API 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](https://openapi-generator.tech/) o [Swagger Codegen](https://swagger.io/tools/swagger-codegen/) per creare client. La dashboard Swagger è inoltre integrata in PowerShell Universal per fornire documentazione interattiva.

## Documentazione dell'API di gestione

È possibile 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 **Build > APIs > Documentation** e poi su Create new Endpoint Documentation. È possibile impostare il nome, l'URL, la descrizione e i dettagli di autenticazione per la documentazione.

Una volta creata, è possibile assegnare gli endpoint alla documentazione modificando l'endpoint.

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

Verranno elencati tutti i suoi endpoint personalizzati.

## Testo della guida

È possibile specificare il testo della guida per le sue API utilizzando la guida basata su commenti. L'inclusione di una sinossi, di una descrizione e delle descrizioni dei parametri farà sì che ciascuno di questi elementi venga documentato nella documentazione OpenAPI e nella pagina Swagger.

Ad esempio, con un semplice endpoint `/get/:id`, potremmo avere una guida basata su commenti come questa.

```powershell
<# 
.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 di documentazione degli endpoint. Clicchi sul pulsante Edit Details nel record della documentazione API.

Le API possono essere documentate anche utilizzando tipi di input e output, creando una classe PowerShell e facendovi riferimento nella guida basata su 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 archiviate in `endpointsDocumentation.ps1`.

```powershell
[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 definita nella documentazione degli endpoint.

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

```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/it/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.