Creación de un Swagger JSON de especificación de programación
Si necesita crear un nuevo archivo JSON de especificación Swagger, puede comenzar con la plantilla proporcionada aquí.
About this task
La plantilla incluye elementos modelo:
| Nombre del campo | Tipo | |
|---|---|---|
| openapi | string | Obligatorio Esta serie debe ser el número de versión semántica de la versión de la especificación OpenAPI que utiliza el documento OpenAPl. Los clientes y las especificaciones de herramientas deben utilizar el campo para interpretar el documento OpenAPI. Esto no está relacionado con la cadena de API. |
| info | Objeto de información | Obligatorio Proporciona metadatos sobre la API. Las herramientas pueden utilizar los metadatos según sea necesario. |
| servidores | Objetos de servidor | Una matriz de objetos de servidor, que proporcionan información de conectividad a un servidor de destino. Si la propiedad no se proporciona, o es una matriz vacía, el valor predeterminado sería un Objeto de servidor con un valor de URL de /. |
| vías de acceso | Objeto de vías de acceso | Obligatorio Las vías de acceso y las operaciones disponibles para la API. |
| componentes | Objeto de componentes | Elemento que contiene varios esquemas para la especificación. |
| security | Objeto de requisitos de seguridad | Declaración de qué mecanismos de seguridad se pueden utilizar en la API. La lista de valores incluye objetos de requisitos de seguridad alternativos que se pueden utilizar. Solo se debe satisfacer uno de los objetos de requisito de seguridad para autorizar una solicitud. Las operaciones individuales pueden anular esta definición. Para que la seguridad sea opcional, se puede incluir un requisito de seguridad vacío en la matriz. |
| códigos | Objeto de etiqueta | Una lista de códigos utilizados por la especificación con metadatos adicionales. El orden de las etiquetas se puede utilizar para reflejar su orden mediante las herramientas de análisis. No se deben declarar todas las etiquetas que utiliza el objeto de operación. Las etiquetas que no se declaran pueden organizarse de forma aleatoria o según la lógica de la herramienta. Cada nombre de etiqueta de la lista debe ser único. |
| externalDocs | Objeto de documentación externa | Documentación adicional externa |
Debe determinar varias cosas antes de crear un nuevo archivo JSON.
- Cuáles son los parámetros que utilizará (se describen a continuación: http://swagger.io/specification/#parameterObject)?
- ¿Qué produce el método que está creando? Trace una lista de tipos de datos que se pueden devolver de la operación.
- ¿Qué consume el método? Trace una lista de tipos de datos consumidos por la operación.
- Cuáles son las respuestas válidas (se describen a continuación: http://swagger.io/specification/#responseObject)?
Para añadir un esquema nuevo, añada un objeto de esquema al objeto de componentes.
Puntos clave a recordar
- El nombre del esquema,
- La estructura del objeto de esquema. Para obtener ayuda, consulte la documentación de Objeto de esquema en la especificación Swagger. Tenga en cuenta que un objeto de esquema puede contener otro objeto de esquema, como referencia a él. Por ejemplo, consulte el campo de dirección. Considere este modelo simple como un ejemplo adicional de un objeto de esquema
Adición de cabeceras a respuestas
Los encabezamientos que se devuelven con respuestas se pueden describir agregando una propiedad de encabezados para cada objeto de respuestas.
Por ejemplo, agregando un encabezamiento llamado Ubicación a la respuesta de una solicitud POST donde se crea un recurso:
Para obtener más información sobre esta especificación, consulte la especificación OpenAPI.
Procedure
- Vaya al Swagger Editor.
- Seleccione el menú desplegable Insertar y seleccione Agregar elementos de vía de acceso para agregar la ruta.
- Añada una operación seleccionando Añadir operación.
- Añada una respuesta seleccionando Añadir respuesta de ejemplo.