> 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 ## Informazioni La documentazione API può essere prodotta 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 una documentazione interattiva. ## Documentazione dell'API di gestione Può 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 APIs \ Documentation e poi su Create new Endpoint Documentation. Può impostare il nome, l'URL, la descrizione e i dettagli di autenticazione per la documentazione.

Finestra di dialogo Endpoint Documentation

Una volta creata, può assegnare gli endpoint alla documentazione modificando l'endpoint.

Modificare l'endpoint

La documentazione del suo endpoint apparirà nella dashboard Swagger. Selezioni la definizione con il menu a discesa Select a definition.
Verranno elencati tutti i suoi endpoint personalizzati. ![Swagger Documentation for APIs](/files/VRhTi9VYQF0NxNbF56mT) ## Testo della guida Può specificare il testo della guida per le sue API utilizzando l'aiuto basato sui commenti. L'inclusione di una sinossi, di una descrizione e delle descrizioni dei parametri farà sì che ognuno di questi elementi venga documentato nella documentazione OpenAPI e nella pagina Swagger. Ad esempio, con un semplice endpoint `/get/:id`, potremmo avere un aiuto basato sui commenti come questo. ```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 della documentazione dell'endpoint. Clicchi sul pulsante Edit Details nel record della documentazione API.

Editor della documentazione dell'endpoint

Le API possono anche essere documentate utilizzando tipi di input e output creando una classe PowerShell e facendovi riferimento nell'aiuto basato sui 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 memorizzate 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 che ha definito nella documentazione dell'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=&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.