OpenAPI
Acerca de
Se puede generar documentación de la API para sus endpoints creando una nueva definición de OpenAPI y asignándole endpoints. OpenAPI es un formato estándar y puede ser consumido por herramientas, como OpenAPI Generator o Swagger Codegen, para crear clientes. El panel de Swagger también está integrado en PowerShell Universal para proporcionar documentación interactiva.
Documentación de la API de gestión
Puede consultar la documentación de la API de gestión visitando el panel de Swagger integrado.
http://localhost:5000/swagger/index.htmlCrear un documento OpenAPI
Para crear una definición de OpenAPI, haga clic en APIs \ Documentation y luego en Create new Endpoint Documentation. Puede establecer el nombre, la URL, la descripción y los detalles de autenticación de la documentación.

Una vez creada, puede asignar endpoints a la documentación editando el endpoint.

La documentación de su endpoint aparecerá en el panel de Swagger. Seleccione la definición con el menú desplegable Select a definition.

Se enumerarán todos sus endpoints personalizados.

Texto de ayuda
Puede especificar texto de ayuda para sus APIs mediante la ayuda basada en comentarios. Incluir una sinopsis, una descripción y descripciones de parámetros hará que cada una de esas partes se documente en la documentación de OpenAPI y en la página de Swagger.
Por ejemplo, con un endpoint sencillo /get/:id, podríamos tener una ayuda basada en comentarios como esta.
La página de Swagger resultante mostrará cada una de estas descripciones.
Tipos de entrada y salida
Los tipos se pueden definir dentro de un ScriptBlock de documentación de endpoint. Haga clic en el botón Edit Details del registro de documentación de la API.

Las APIs también se pueden documentar mediante tipos de entrada y salida creando una clase de PowerShell y haciendo referencia a ella en su ayuda basada en comentarios. PowerShell Universal aprovecha las secciones .INPUTS y .OUTPUTS para especificar los formatos aceptados y definir los valores de retorno de los códigos de estado.
Dentro de .INPUTS y .OUTPUTS, definirá un bloque YAML para proporcionar esta información. Para crear tipos, utilice el editor de documentación de endpoints. Este fichero se carga al leer documentos OpenAPI. Esta información se almacena en endpointsDocumentation.ps1.
Entradas
Los tipos de entrada se definen en la sección .INPUTS. Esta sección es un bloque YAML que define si la entrada es obligatoria, proporciona una descripción y especifica el tipo de contenido. Se trata de un tipo de contenido seguido de la clase de PowerShell que definió en la documentación del endpoint.
Salidas
Los tipos de salida son similares a los de entrada, pero se especifican en los códigos de retorno, así como su tipo de contenido y su clase de PowerShell. El siguiente ejemplo devuelve una clase ADAccountType cuando la API devuelve un HTTP OK (200). Un 400 (Bad Request) no devuelve datos, pero sí proporciona una descripción que se mostrará en la documentación de la API.
Última actualización
¿Te fue útil?