Especificaciones

La página Especificaciones es donde diseñas y guardas el contrato de una API: documentos OpenAPI (OpenAPI 3.0 y 3.1, y Swagger 2.0) y los archivos .proto de los servicios gRPC. Echolot comprueba una especificación mientras la editas, la convierte en solicitudes que se mantienen al día con ella y la sirve como mock antes de que exista la API.

Ábrela con Especificaciones en el selector de módulos de la barra lateral, o con ⌘3.

Especificaciones en el espacio de trabajoCopy Anchor Link

Las especificaciones son archivos de la carpeta specs del espacio de trabajo, así que van a Git con todo lo demás. El ejemplo Alpenglow tiene tres: alpenglow.yaml (el documento OpenAPI de la tienda), shop.graphql e inventory.proto. La página Especificaciones lista los documentos OpenAPI en Especificaciones y los archivos .proto en Archivos proto. Los esquemas GraphQL de la carpeta los usan las solicitudes GraphQL y no aparecen aquí.

El + de la cabecera Especificaciones de la barra lateral añade una:

Importar un documento OpenAPI con Archivo › Importar… es distinto: crea solicitudes a partir de él, no una especificación que editar.

Haz clic con el botón derecho en una especificación para ver Generar solicitudes, Mostrar en el Finder, Exportar (En YAML… o En JSON…) y Eliminar…. Eliminar pregunta antes y traslada el archivo a la papelera; los archivos a los que hace referencia se quedan, y también sus mocks.

El esquemaCopy Anchor Link

Haz clic en una especificación para abrirla. Debajo de la lista, la barra lateral muestra su esquema:

• Visión general, el título, la versión y la descripción.
• ENDPOINTS, todas las operaciones con su método y su ruta. Las obsoletas aparecen tachadas. Sitúa el puntero sobre una para ver su resumen.
• ESQUEMAS, los esquemas reutilizables.
• Archivos, cuando la especificación hace referencia a otros archivos (consulta Especificaciones divididas en varios archivos).

Haz clic en una entrada para abrirla: en el editor visual se abre su tarjeta y se desplaza hasta verla; en el código, el editor va a su línea.

Visual y códigoCopy Anchor Link

El interruptor Editor de la cabecera de la página elige cómo ves la especificación abierta:

• Visual: tarjetas para la visión general, los servidores, los endpoints y los esquemas, que se editan con campos y menús.
• Código: el documento como YAML o JSON, con números de línea.

Los dos editan el mismo texto, y Echolot lo guarda poco después de cada cambio. Editar una especificación explica ambos.

ProblemasCopy Anchor Link

Echolot valida la especificación mientras la editas. La barra que hay sobre el editor muestra Sin problemas, o el número de errores y advertencias. Un recuento de errores en rojo aparece también junto a la especificación abierta en la barra lateral.

Haz clic en él para ver la lista: primero los errores, luego las advertencias y las sugerencias, cada uno con su línea. Elige uno para ir a esa línea. Cuando la lista está vacía, dice que el documento sigue la especificación OpenAPI y que todas las referencias se resuelven.

Qué busca la validación, entre otras cosas:

• Una versión de openapi que Echolot lee, info con un título y una versión, y rutas que empiezan por /.
• Parámetros de ruta que están en la ruta y marcados como required: true, y parámetros que no están definidos dos veces.
• Una descripción en cada respuesta, y operation IDs que se usan una sola vez.
• Etiquetas declaradas arriba, esquemas de seguridad que están definidos, arrays con items y enumeraciones con valores.
• Referencias que apuntan a algo, en este archivo o en otro de specs.
• Ningún servers: las solicitudes creadas a partir de la especificación empiezan entonces por {{baseUrl}}, que defines tú.

La herramienta de línea de comandos ejecuta la misma validación en CI: consulta echolot spec.

Especificaciones divididas en varios archivosCopy Anchor Link

Una especificación puede incorporar partes de otros archivos con $ref, como $ref: schemas/pet.yaml#/Pet. Los archivos deben estar dentro de la carpeta specs del espacio de trabajo. La barra lateral los lista en Archivos: haz clic en uno para abrirlo en Código. En el editor de código, sitúa el puntero sobre un $ref para ver a qué apunta, y haz clic en él con ⌘ pulsada para ir allí, en este archivo o en el otro.

Echolot lee las partes juntas dondequiera que usa la especificación: validación, generación de solicitudes, mocks. Al exportar la especificación, los archivos a los que hace referencia se escriben en el único archivo que guardas.

ExportarCopy Anchor Link

Exportar en la barra que hay sobre el editor (Exportar en YAML… o Exportar en JSON…) guarda la especificación como un único archivo fuera del espacio de trabajo, con los archivos a los que hace referencia escritos dentro. Los cambios sin guardar se guardan antes, así que la exportación es lo que muestra el editor.

Solicitudes que siguen la especificaciónCopy Anchor Link

Generar solicitudes en la barra que hay sobre el editor crea una carpeta con el nombre de la especificación, con una solicitud por cada endpoint, y abre la primera. La carpeta sigue la especificación: cuando esta cambia, puedes aplicar los cambios a sus solicitudes sin perder lo que editaste en ellas.

Cuando una carpeta sigue la especificación, el botón pasa a ser Solicitudes, un menú con Buscar cambios en “carpeta”… para cada carpeta que la sigue, y Generar otra carpeta. Buscar cambios abre Sincronización OpenAPI, que lista lo que es Nueva en la especificación, Cambiada en la especificación y Ya no está en la especificación. Marca los cambios que quieras y haz clic en Aplicar 1 cambio (o Aplicar 3 cambios, y así sucesivamente). Tus ediciones se conservan siempre; cuando tú y la especificación cambiasteis lo mismo, se conserva lo tuyo. Cuando una operación ya no existe, su solicitud va a la papelera, salvo que la hayas editado: entonces se queda y deja de seguir la especificación. Desvincular hace que la carpeta deje de seguir la especificación y deja sus solicitudes como están.

Una carpeta también puede seguir una especificación de fuera del espacio de trabajo, un archivo o una URL: haz clic con el botón derecho en la carpeta en la barra lateral Solicitudes y elige Vincular a una especificación OpenAPI…. La herramienta de línea de comandos comprueba y aplica cambios con echolot spec check y echolot spec apply.