> 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() ``` ### Vedere anche * [Devolutions Academy – Creazione di un endpoint che accetta un corpo](https://academy.devolutions.net/student/activity/3466020-creating-an-endpoint-that-accepts-a-body) * [Devolutions Academy – Diversi metodi di route](https://academy.devolutions.net/student/activity/3466022-different-route-methods) --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.