Primera API en la interfaz de usuario de Swagger

Swagger UI es una herramienta de código abierto que genera una interfaz de usuario para una especificación OpenAPI, lo que permite a los usuarios visualizar e interactuar con los puntos finales de la API. La herramienta es desarrollada y mantenida por el proyecto Swagger, que ahora es parte de la Iniciativa OpenAPI más grande.

La interfaz de usuario de Swagger se puede utilizar para probar y explorar rápidamente una API sin necesidad de herramientas o software adicionales. Una vez que se proporciona una especificación de OpenAPI, la interfaz de usuario de Swagger genera una página de documentación interactiva que incluye información sobre los puntos finales, parámetros, respuestas y más de la API. La interfaz de usuario se genera dinámicamente en función de la información proporcionada en la especificación, lo que significa que los cambios realizados en la API se reflejarán automáticamente en la documentación.

Además de proporcionar capacidades de documentación y prueba, la interfaz de usuario de Swagger también admite varias funciones, como el resaltado de sintaxis, la validación de respuestas y la generación de código. La herramienta se puede utilizar con las API creadas con cualquier lenguaje de programación y se puede personalizar para que coincida con la marca y el estilo de la API.

Hoy agregaremos nuestra primera API en Swagger UI.

campo de servidor

En una especificación de OpenAPI, el objeto de servidor se usa para definir información sobre el servidor que aloja la API. El objeto del servidor incluye varios campos que se pueden usar para proporcionar información, como la URL, el protocolo y la descripción del servidor. Estos son los campos que se pueden incluir en un objeto de servidor:

url: este campo especifica la URL base del servidor. Es un campo obligatorio y debe incluirse en el objeto del servidor.

description: este campo proporciona una descripción del servidor. Es un campo opcional y se puede incluir para proporcionar información adicional sobre el servidor.

variables: este campo se utiliza para definir variables que se pueden utilizar en el campo de URL. Las variables están encerradas entre llaves ({}) y se pueden usar para representar partes de la URL que se pueden personalizar para diferentes entornos o casos de uso.

scheme: este campo especifica el protocolo de comunicación utilizado por el servidor (por ejemplo, HTTP, HTTPS, etc.). Es un campo opcional y el valor predeterminado es "http" si no se especifica.

headers: este campo se utiliza para especificar los encabezados que deben incluirse en las solicitudes al servidor. Es un campo opcional y se puede utilizar para proporcionar información adicional o credenciales de autenticación.

Aquí hay un ejemplo de un objeto de servidor con todos los campos incluidos:

"servers": [
  {
    "url": "https://api.example.com/{version}",
    "description": "Example API Server",
    "variables": {
      "version": {
        "enum": ["v1", "v2"],
        "default": "v1"
      }
    },
    "scheme": "https",
    "headers": {
      "X-API-Key": {
        "description": "API key",
        "required": true
      }
    }
  }
]

Aquí hay un ejemplo de un objeto de servidor para nuestra primera API. Agregar un servidor.

Campo de etiqueta

En una especificación de OpenAPI, el objeto de etiqueta se usa para definir una etiqueta para un conjunto de operaciones relacionadas. El objeto de etiqueta incluye varios campos que se pueden usar para proporcionar información, como el nombre de la etiqueta, la descripción y las operaciones asociadas. Estos son los campos que se pueden incluir en un objeto de etiqueta:

name: este campo especifica el nombre de la etiqueta. Es un campo obligatorio y debe incluirse en el objeto de etiqueta.

description: este campo proporciona una descripción de la etiqueta. Es un campo opcional y se puede incluir para proporcionar información adicional sobre la etiqueta.

externalDocs: este campo proporciona una referencia a documentación adicional para la etiqueta. Es un campo opcional y se puede utilizar para proporcionar información adicional o recursos relacionados con la etiqueta.

x-tag-info: este campo es un campo de extensión que se puede utilizar para proporcionar información adicional sobre la etiqueta. Es un campo opcional y se puede utilizar para proporcionar información personalizada o metadatos sobre la etiqueta.

Este es un ejemplo de un objeto de etiqueta con todos los campos incluidos:

"tags": [
  {
    "name": "pets",
    "description": "Operations related to pets",
    "externalDocs": {
      "description": "Find more info here",
      "url": "https://example.com/pets/info"
    },
    "x-tag-info": {
      "owner": "John Smith"
    }
  }
]

Aquí hay un ejemplo de un objeto de etiqueta para nuestra primera API. Añadir una etiqueta.

campo de esquema

En una especificación de OpenAPI, el objeto de esquema se utiliza para describir la estructura y los tipos de datos de un objeto. El objeto de esquema incluye varios campos que se pueden usar para proporcionar información, como el tipo, el formato y las propiedades del esquema. Estos son los campos que se pueden incluir en un objeto de esquema:

title: este campo especifica el título del esquema. Es un campo opcional y se puede incluir para proporcionar un título legible para el esquema.

type: este campo especifica el tipo de esquema. Es un campo obligatorio y puede ser uno de varios valores posibles, como "cadena", "número", "entero", "booleano", "matriz" u "objeto".

format: este campo especifica el formato del esquema. Es un campo opcional y se puede utilizar para especificar más el tipo de datos del esquema. Por ejemplo, si el tipo es "cadena", el campo de formato se puede usar para indicar que la cadena es una fecha o una hora.

description: este campo proporciona una descripción del esquema. Es un campo opcional y se puede incluir para proporcionar información adicional sobre el esquema.

properties: este campo especifica las propiedades de un esquema de objeto. Es un campo opcional y se puede utilizar para definir las propiedades y los tipos de datos de las propiedades de un objeto.

items: este campo especifica el esquema de los elementos de una matriz. Es un campo opcional y se puede utilizar para definir el tipo de datos de los elementos de una matriz.

required: este campo especifica las propiedades requeridas de un esquema de objeto. Es un campo opcional y se puede utilizar para especificar qué propiedades de un esquema de objeto son necesarias.

example: este campo proporciona un ejemplo del esquema. Es un campo opcional y se puede utilizar para proporcionar un valor de ejemplo para el esquema.

Aquí hay un ejemplo de un objeto de esquema con todos los campos incluidos:

{
  "type": "object",
  "title": "Person",
  "description": "A person schema",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "John Smith",
    "age": 30,
    "email": "john.smith@example.com"
  }
}

Aquí hay un ejemplo de un objeto de esquema para nuestra primera API. Agregar un esquema.

campo de caminos

En una especificación de OpenAPI, el objeto de rutas se usa para definir los puntos finales (o rutas) disponibles y las operaciones en esos puntos finales. El objeto de rutas es un mapa clave-valor donde las claves son las rutas de puntos finales y los valores son objetos de elementos de ruta. Estos son los campos que se pueden incluir en un objeto de elemento de ruta:

Método HTTP: existen varios métodos HTTP, como GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS y TRACE. Este campo especifica el método HTTP que admite el punto final.

summary: este campo proporciona un breve resumen de la operación del punto final.

description: este campo proporciona una descripción detallada de la operación del punto final.

parameters: este campo especifica los parámetros que acepta la operación de punto final. Puede ser una matriz de objetos de parámetro o una referencia a una definición de parámetro.

requestBody: este campo especifica el cuerpo de la solicitud que espera la operación de punto final. Es un campo opcional y puede ser un objeto RequestBody o una referencia a una definición de cuerpo de solicitud.

responses: este campo especifica las posibles respuestas que puede devolver la operación de punto final. Es un mapa clave-valor donde las claves son los códigos de estado HTTP y los valores son objetos de respuesta.

callbacks: este campo especifica un mapa de posibles devoluciones de llamadas relacionadas con la operación principal. Cada valor en el mapa es un objeto de devolución de llamada.

deprecated: este campo indica si la operación de punto final está obsoleta y no debe utilizarse.

Este es un ejemplo de un objeto de elemento de ruta que incluye todos estos campos:

{
  "/pets": {
    "get": {
      "summary": "Get a list of pets",
      "description": "Returns a list of pets that are available for adoption.",
      "parameters": [
        {
          "name": "limit",
          "in": "query",
          "description": "The maximum number of pets to return.",
          "required": false,
          "schema": {
            "type": "integer"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        },
        "400": {
          "description": "Invalid input."
        },
        "401": {
          "description": "Unauthorized."
        },
        "500": {
          "description": "Server error."
        }
      }
    }
  }
}

Aquí hay un ejemplo de un objeto de rutas para nuestra primera API. Agregar rutas.

La interfaz de usuario de Swagger se puede usar para probar rápidamente

ElTry it out La característica de la interfaz de usuario de Swagger permite a los usuarios interactuar con una API mediante el envío de solicitudes y la recepción de respuestas. Proporciona una interfaz de usuario para probar la API sin tener que escribir código o usar una herramienta separada.

Cuando haces clic en elTry it out junto a una operación de API en la interfaz de usuario de Swagger, puede ingresar valores para los parámetros de la operación y enviar una solicitud a la API. La interfaz de usuario de Swagger mostrará la respuesta que devuelve la API. Esto le permite probar y validar rápidamente el comportamiento de una API sin tener que salir de la interfaz de usuario de Swagger.

ElTry it out La función también puede ayudarlo a explorar las capacidades de una API y comprender cómo usarla de manera efectiva. Al interactuar con una API en tiempo real, puede ver cómo responde a diferentes solicitudes y obtener más información sobre los datos que devuelve.

Aquí hay un ejemplo deTry it out para nuestra primera API. Try it out