Editor Swagger

El editor Swagger se utiliza para editar el diseño de la API utilizando YAML o JSON. Para acceder al editor, hacer clic en el icono del logo oficial de Swagger, ubicado en la tarjeta de una API, en la página API Catalog:

No acceder al editor de Swagger por otra ruta que no sea haciendo clic en el icono Swagger (por ejemplo, abriendo más de una pestaña o ventana del navegador). Esto hará que el editor funcione mal.

Modificaciones en la API

Mientras edita el diseño de la API, el editor monitorea posibles errores de acuerdo con la estructura estándar de Swagger y los muestra en la pantalla de vista previa ubicada en el lado derecho.

Si hay algún error, los botones SAVE y SAVE AS NEW REVISION se desactivarán, lo que significa que no será posible guardar los cambios hasta que se hayan corregido los errores indicados.

La siguiente imagen muestra un error relacionado con el host: no contiene una ruta base (sería correcto introducir un valor, como "/petstore/v3"). Si tiene alguna duda sobre la especificación de Swagger, acceda a esta página).

El editor contiene toda la información relacionada con la API. Cuando se guarda esta información, el Manager almacena el contenido del editor y actualiza la información básica de recursos y operaciones dentro del sistema.

Desde el editor Swagger de la API, puede descargar el archivo Swagger, generar un servidor y generar un cliente.

El host definido en el editor no afecta el registro de API en el Manager, es decir, solo se refiere al archivo Swagger, el resto del contenido es el mismo que de la API. El registro de API admite varias URL, tanto para producción como para entorno limitado, por lo que los hosts se manejan de forma independiente.

Escenario de error

Editor A y B exhiben la misma API

El usuario realiza cambios en el editor A y guarda la información correctamente; más adelante, el mismo usuario realiza cambios en el editor B. En consecuencia, la información de la API se sobrescribe.

Guarda de las modificaciones

Existen dos opciones para guardar las modificaciones realizadas en el editor, situadas en la esquina superior derecha de la pantalla:

SAVE: permite guardar los cambios realizados sobreescribiendo la revisión actual de la API, es decir, sin generar una nueva revisión.
SAVE AS NEW REVISION: guarda los cambios creando una nueva revisión para la API.

Después de guardar el Swagger, el usuario es redirigido a la pantalla de éxito en el Manager, donde puede crear un plan o descargar el archivo Swagger.

Tenga cuidado al guardar los cambios en la misma revisión. Si hay algún error en el cambio, una API desplegada en producción podría verse afectada negativamente, lo que resultaría en fallas o interrupciones del servicio. Asegúrese de revisar cuidadosamente todos los cambios antes de guardarlos en la misma revisión.
Los hosts de descarga de Swagger en el Manager y en el editor no están vinculados, a menos que estén registrados con el mismo dominio en ambas ubicaciones.

En caso de error al guardar la API, se mostrará un mensaje en en la pantalla de vista previa del editor. En la imagen siguiente, por ejemplo, el mensaje de error se generó debido a la falta de un recurso registrado en el Manager, pero no presente en el archivo Swagger.

Descargar el archivo Swagger

Puede descargar el archivo Swagger de una API en dos formatos: YAML o JSON. Para esto, hacer clic en el botón File y eligir entre Save as YAML o Convert and save as JSON.

Generar servidores

En Generate Server, puede generar la estructura básica de un servidor para la exposición de API.

Generar client/SDKs

Al hacer clic en Generate Client, puede generar un SDK en varios idiomas para consumir recursos de APIs, acelerando así el proceso de desarrollo.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]