> 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/de/api/openapi.md). # OpenAPI ## Über API-Dokumentation kann für Ihre Endpunkte erstellt werden, indem Sie eine neue OpenAPI-Definition erstellen und ihr Endpunkte zuweisen. OpenAPI ist ein Standardformat und kann von Werkzeugen wie dem [OpenAPI Generator](https://openapi-generator.tech/) oder [Swagger Codegen](https://swagger.io/tools/swagger-codegen/) genutzt werden, um Clients zu erstellen. Das Swagger-Dashboard ist ebenfalls in PowerShell Universal integriert, um interaktive Dokumentation bereitzustellen. ## Dokumentation der Management-API Sie können die Dokumentation der Management-API einsehen, indem Sie das integrierte Swagger-Dashboard besuchen. ``` http://localhost:5000/swagger/index.html ``` ## Ein OpenAPI-Dokument erstellen Um eine OpenAPI-Definition zu erstellen, klicken Sie auf APIs \ Documentation und dann auf Create new Endpoint Documentation. Sie können den Namen, die URL, die Beschreibung und die Authentifizierungsdetails für die Dokumentation festlegen.

Nach der Erstellung können Sie der Dokumentation Endpunkte zuweisen, indem Sie den Endpunkt bearbeiten.

Die Dokumentation für Ihren Endpunkt erscheint im Swagger-Dashboard. Wählen Sie die Definition über das Dropdown-Menü Select a definition aus.

Alle Ihre benutzerdefinierten Endpunkte werden aufgelistet. ![Swagger Documentation for APIs](/files/ITeFeyDIfkAfpqQNT3HK) ## Hilfetext Sie können Hilfetext für Ihre APIs mithilfe kommentarbasierter Hilfe angeben. Wenn Sie eine Übersicht, eine Beschreibung und Parameterbeschreibungen einschließen, werden all diese Bestandteile in der OpenAPI-Dokumentation und auf der Swagger-Seite dokumentiert. Zum Beispiel könnten wir bei einem einfachen `/get/:id`-Endpunkt eine kommentarbasierte Hilfe wie diese haben. ```powershell <# .SYNOPSIS This is an endpoint .DESCRIPTION This is a description .PARAMETER ID This is an ID. #> param($ID) $Id ``` Die resultierende Swagger-Seite zeigt jede dieser Beschreibungen an. ## Eingabe- und Ausgabetypen Typen können innerhalb eines ScriptBlocks der Endpunkt-Dokumentation definiert werden. Klicken Sie auf die Schaltfläche Edit Details im API-Dokumentationsdatensatz.

APIs können auch mit Eingabe- und Ausgabetypen dokumentiert werden, indem Sie eine PowerShell-Klasse erstellen und in Ihrer kommentarbasierten Hilfe darauf verweisen. PowerShell Universal nutzt die Abschnitte `.INPUTS` und `.OUTPUTS`, um akzeptierte Formate anzugeben und Rückgabewerte für Statuscodes zu definieren. Innerhalb von `.INPUTS` und `.OUTPUTS` definieren Sie einen YAML-Block, um diese Informationen bereitzustellen. Verwenden Sie zum Erstellen von Typen den Editor für Endpunkt-Dokumentation. Diese Datei wird beim Lesen von OpenAPI-Dokumenten geladen. Diese Informationen werden in `endpointsDocumentation.ps1` gespeichert. ```powershell [Documentation()] class MyReturnType { [string]$Value } ``` ### Eingaben Eingabetypen werden im Abschnitt `.INPUTS` definiert. Dieser Abschnitt ist ein YAML-Block, der definiert, ob die Eingabe erforderlich ist, eine Beschreibung bereitstellt und den Content-Type angibt. Dies ist ein Content-Type, gefolgt von der PowerShell-Klasse, die Sie in der Endpunkt-Dokumentation definiert haben. ```powershell <# .INPUTS Required: false Description: This is an input value. Content: application/json: MyReturnType #> param() ``` ### Ausgaben Ausgabetypen sind den Eingaben ähnlich, werden jedoch für Rückgabecodes sowie deren Content-Type und PowerShell-Klasse angegeben. Das folgende Beispiel gibt eine ADAccountType-Klasse zurück, wenn die API ein HTTP OK (200) zurückgibt. Ein 400 (Bad Request) gibt keine Daten zurück, stellt aber eine Beschreibung bereit, die in der API-Dokumentation angezeigt wird. ```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/de/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.