OpenAPI
Standardized documentation for your endpoints.
Last updated
Was this helpful?
Standardized documentation for your endpoints.
Last updated
Was this helpful?
API documentation can be produced for your endpoints by creating a new OpenAPI definition and assigning endpoints to it. OpenAPI is a standard format and can be consumed by tools, such as the OpenAPI Generator or Swagger Codegen, to create clients. The Swagger dashboard is also integrated into PowerShell Universal to provide interactive documentation.
You can view the Managment API documentation by visiting the built in Swagger dashboard.
To create an OpenAPI definition, click APIs \ Documentation and then Create new Endpoint Documentation. You can set the name, URL, description and authentication details for the documentation.
Once created, you can assign endpoints to the documentation by editing the endpoint.
The documentation for your endpoint will appear within the Swagger dashboard. Select the definition with the Select a definition dropdown.
All your custom endpoints will be listed.
You can specify help text for your APIs using comment-based help. Including a synopsis, description and parameter descriptions will result in each of those pieces being documented in the OpenAPI documentation and Swagger age.
For example, with a simple /get/:id endpoint, we could have comment-based help such as this.
The resulting Swagger page will show each of these descriptions.
Types can be defined within an endpoint documentation ScriptBlock. Click the Edit Details button on the API documentation record.
APIs can also be documented using input and output types by creating a PowerShell class and referencing it within your comment-based help. PowerShell Universal takes advantage of the .INPUTS and .OUTPUTS sections to specify accepted formats and define status code return values.
Within the .INPUTS and .OUTPUTS , you will define a YAML block to provide this information. To create types, use the Endpoint Documentation editor. This file is loaded when reading OpenAPI documents. This information is stored in endpointsDocumentation.ps1.
Input types are defined in the .INPUTS section. This section is a YAML block that defines if the input is required, provides a description and specifies the content type. This is a content type followed by the PowerShell class you defined in the endpoint documentation.
Output types are similar to input but are specified on return codes as well as their content type and PowerShell class. The below example returns an ADAccountType class when a HTTP OK (200) is returned from the API. A 400 (Bad Request) does not return data but does provide a description that will be displayed in the API documentation.
