¿Para qué se utiliza Swagger?

Swagger (ahora OpenAPI Specification) se utiliza para describir, documentar y visualizar API RESTful. Esto permite a los desarrolladores, probadores y consumidores de API entender la funcionalidad del servicio sin acceso al código fuente.

Funciones principales:

1. Documentación: Creación automática de documentación interactiva de API.
2. Desarrollo: Ayuda en el desarrollo de API, proporcionando una definición clara del contrato.
3. Pruebas: La interfaz Swagger (Swagger UI) permite probar los puntos finales de API directamente desde el navegador.
4. Generación de código: Se puede generar código cliente (SDK) o servidores simulados basados en la especificación OpenAPI.
5. Diseño: Puede usarse como una herramienta para diseñar API antes de comenzar a codificar (Enfoque de Diseño-Primero).

Ejemplo de fragmento de especificación en formato YAML:

# Descripción corta de API
openapi: 3.0.0
info:
  title: Mi API de prueba
  version: 1.0.0
paths:
  /items:
    get:
      summary: Obtener la lista de todos los elementos
      responses:
        '200':
          description: Lista de elementos obtenida con éxito
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

Esto garantiza la coherencia entre las diferentes partes involucradas en el desarrollo y uso de API.