> 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/fr/api/openapi.md). # OpenAPI Générez de la documentation OpenAPI pour les terminaux PowerShell Universal, ajoutez de l'aide basée sur les commentaires et définissez les types d'entrée et de sortie pour le tableau de bord Swagger. ## À propos La documentation de l'API peut être produite pour vos terminaux en créant une nouvelle définition OpenAPI et en lui assignant des terminaux. OpenAPI est un format standard qui peut être utilisé par des outils, tels que le [OpenAPI Generator](https://openapi-generator.tech/) ou [Swagger Codegen](https://swagger.io/tools/swagger-codegen/), pour créer des clients. Le tableau de bord Swagger est également intégré à PowerShell Universal pour fournir une documentation interactive. ## Documentation de l'API de gestion Vous pouvez consulter la documentation de l'API de gestion en visitant le tableau de bord Swagger intégré. ``` http://localhost:5000/swagger/index.html ``` ## Créer un document OpenAPI Pour créer une définition OpenAPI, cliquez sur **Build > APIs > Documentation**, puis sur Create new Endpoint Documentation. Vous pouvez définir le nom, l'URL, la description et les détails d'authentification de la documentation. Une fois créée, vous pouvez assigner des terminaux à la documentation en modifiant le terminal. La documentation de votre terminal apparaîtra dans le tableau de bord Swagger. Sélectionnez la définition à l'aide de la liste déroulante Select a definition. Tous vos terminaux personnalisés seront listés. ## Texte d'aide Vous pouvez spécifier du texte d'aide pour vos API à l'aide de l'aide basée sur les commentaires. L'inclusion d'un synopsis, d'une description et de descriptions de paramètres fera en sorte que chacun de ces éléments soit documenté dans la documentation OpenAPI et la page Swagger. Par exemple, avec un simple terminal `/get/:id`, nous pourrions avoir une aide basée sur les commentaires comme celle-ci. ```powershell <# .SYNOPSIS This is an endpoint .DESCRIPTION This is a description .PARAMETER ID This is an ID. #> param($ID) $Id ``` La page Swagger résultante affichera chacune de ces descriptions. ## Types d'entrée et de sortie Les types peuvent être définis dans un ScriptBlock de documentation de terminal. Cliquez sur le bouton Edit Details de l'enregistrement de documentation de l'API. Les API peuvent aussi être documentées à l'aide de types d'entrée et de sortie en créant une classe PowerShell et en la référençant dans votre aide basée sur les commentaires. PowerShell Universal tire parti des sections `.INPUTS` et `.OUTPUTS` pour spécifier les formats acceptés et définir les valeurs de retour des codes de statut. Dans les sections `.INPUTS` et `.OUTPUTS`, vous définirez un bloc YAML pour fournir cette information. Pour créer des types, utilisez l'éditeur Endpoint Documentation. Ce fichier est chargé lors de la lecture des documents OpenAPI. Cette information est stockée dans `endpointsDocumentation.ps1`. ```powershell [Documentation()] class MyReturnType { [string]$Value } ``` ### Entrées Les types d'entrée sont définis dans la section `.INPUTS`. Cette section est un bloc YAML qui définit si l'entrée est requise, fournit une description et spécifie le type de contenu. Il s'agit d'un type de contenu suivi de la classe PowerShell que vous avez définie dans la documentation du terminal. ```powershell <# .INPUTS Required: false Description: This is an input value. Content: application/json: MyReturnType #> param() ``` ### Sorties Les types de sortie sont semblables aux types d'entrée, mais sont spécifiés sur les codes de retour ainsi que sur leur type de contenu et leur classe PowerShell. L'exemple ci-dessous retourne une classe ADAccountType lorsqu'un HTTP OK (200) est retourné par l'API. Un 400 (Bad Request) ne retourne pas de données, mais fournit une description qui sera affichée dans la documentation de l'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/fr/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.