Swagger-PHP es siempre lo primero que me viene a la mente cuando pienso en generar una especificación Swagger para un proyecto php. Entonces, ¿qué es Swagger-PHP? ¿Cómo se crean especificaciones usando Swagger-php? En este artículo, abordaremos estas preguntas y te presentaremos los detalles.

¿Qué es Swagger-PHP?

swagger-PHP es una herramienta para generar documentación de API utilizando Swagger (ahora conocido como la Especificación OpenAPI) en PHP. swagger-php ayuda a los desarrolladores de PHP a crear documentación de API basada en la especificación Swagger (OpenAPI). Esta herramienta puede generar especificaciones Swagger (OpenAPI) a partir de código PHP. Permite a los desarrolladores definir puntos finales de API, solicitudes y respuestas en el código, y generar automáticamente una especificación Swagger (OpenAPI).

Características de Swagger-PHP

Swagger-PHP es una herramienta poderosa que se utiliza para generar especificaciones para las versiones 3.0 y 3.1 de OpenAPI. También es capaz de registrar API utilizando código fuente PHP. El atributo de anotación utilizado por Swagger-php puede ser bloques doc o php 8.1, lo que lo hace muy flexible y versátil.

Ya sea que estés trabajando con bloques doc o con la última versión de PHP, Swagger-php puede ayudarte a optimizar tu proceso de desarrollo de API y hacerlo más eficiente en general.

Cómo instalar y configurar Swagger-PHP

Para empezar a usar Swagger-PHP, primero debes instalarlo. Swagger-PHP se puede instalar usando Composer, un administrador de dependencias para PHP.

Para instalar Swagger-PHP, ejecuta el siguiente comando en tu terminal:

composer require zircote/swagger-php

Una vez instalado, puedes empezar a usar Swagger-PHP para generar documentación Swagger para tu API.

A continuación, debes configurar Swagger-PHP creando una nueva instancia de Swagger y configurándola con la información de tu API. Aquí tienes un ejemplo de cómo configurar Swagger-PHP:

require_once('vendor/autoload.php');

use Swagger\Annotations as SWG;

/**
 * @SWG\Swagger(
 *     basePath="/api",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="My API",
 *         description="API documentation for My API",
 *         @SWG\Contact(name="My Company"),
 *         @SWG\License(name="MIT")
 *     )
 * )
 */

En este ejemplo, hemos creado una nueva instancia de Swagger y la hemos configurado con la información de nuestra API, como la ruta base, los esquemas y la información de la API (versión, título, descripción, contacto y licencia).

Una vez que hayas configurado Swagger-PHP, puedes empezar a añadir anotaciones Swagger a tu código API para generar documentación Swagger. Cubriremos esto con más detalle en la siguiente sección.

Creación de documentación Swagger con Swagger-PHP

Swagger-PHP es una biblioteca PHP para generar documentos Swagger. En esta sección, aprenderemos a crear documentación Swagger utilizando Swagger-PHP.

Paso 1. Definición de la información de la API

Primero, necesitamos definir la información de la API. Esto incluye el título, la descripción, la versión, etc. de la API. El siguiente es un ejemplo:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ]);

Paso 2. Definición de los puntos finales de la API

A continuación, necesitamos definir los puntos finales de la API. Esto incluye los métodos HTTP, las rutas, los parámetros y las respuestas para cada punto final. El siguiente es un ejemplo:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'Get a list of users.',
        'description' => 'Returns a list of users.',
        'responses' => [
            '200' => [
                'description' => 'A list of users.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'Create a new user.',
        'description' => 'Creates a new user.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'The user to create.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'The created user.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ]);

Paso 3. Definición del modelo de datos

Por último, necesitamos definir los modelos de datos. Esto incluye los atributos y los tipos de cada modelo. El siguiente es un ejemplo:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'Get a list of users.',
        'description' => 'Returns a list of users.',
        'responses' => [
            '200' => [
                'description' => 'A list of users.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'Create a new user.',
        'description' => 'Creates a new user.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'The user to create.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'The created user.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ])
    ->definitions([
        'User' => [
            'type' => 'object',
            'properties' => [
                'id' => [
                    'type' => 'integer',
                    'format' => 'int64'
                ],
                'name' => [
                    'type' => 'string'
                ],
                'email' => [
                    'type' => 'string'
                ]
            ]
        ]
    ]);

Paso 4. Exportación de documentos Swagger

Por último, podemos generar la documentación Swagger utilizando el siguiente código:

header('Content-Type: application/json');
echo $swagger->toJson();

Esto generará un documento Swagger en formato JSON que se puede utilizar para generar documentación de API.

Integración de Swagger UI con Swagger-PHP

Para aprovechar al máximo los beneficios de la documentación Swagger, es importante tener una interfaz fácil de usar para ver e interactuar con la documentación. Aquí es donde entra Swagger-ui. Swagger-UI es una interfaz basada en la web que proporciona una experiencia interactiva para ver y probar la documentación Swagger.

La integración de Swagger-UI con Swagger-PHP es un proceso sencillo. Primero, descarga la última versión de Swagger-UI del repositorio oficial de GitHub. A continuación, extrae el contenido del archivo descargado a un directorio de tu servidor web.

A continuación, crea un nuevo archivo PHP que servirá como punto de entrada para Swagger-UI. En este archivo, incluye los archivos CSS y JavaScript necesarios para Swagger-UI, así como la propia biblioteca JavaScript de Swagger-ui. También tendrás que incluir el archivo JSON generado por Swagger-PHP que contiene la documentación de tu API.

<!DOCTYPE html>
<html>
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="path/to/swagger-ui.css">
  <script type="text/javascript" src="path/to/swagger-ui-bundle.js"></script>
  <script type="text/javascript" src="path/to/swagger-ui-standalone-preset.js"></script>
</head>
<body>
  <div id="swagger-ui"></div>
  <script type="text/javascript">
    window.onload = function() {
      // Build a system
      const ui = SwaggerUIBundle({
        url: "path/to/swagger-json.php",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout"
      })
    }
  </script>
</body>
</html>

En el ejemplo anterior, sustituye los marcadores de posición path/to por las rutas reales a los archivos CSS y JavaScript de Swagger-UI, así como al archivo JSON generado por Swagger-PHP.

Una vez que hayas creado este archivo, puedes acceder a Swagger-UI navegando a su URL en tu navegador web. Deberías ver una interfaz Swagger-ui totalmente funcional que muestra la documentación de tu API y te permite interactuar con ella.

En conclusión, la integración de Swagger-UI con Swagger-PHP es un proceso sencillo que mejora enormemente la usabilidad de la documentación de tu API. Siguiendo los pasos descritos anteriormente, puedes crear fácilmente una interfaz fácil de usar para la documentación de tu API que facilitará a los desarrolladores la comprensión y el uso de tu API.

Compartir especificaciones de API

Después de generar la especificación Swagger, a menudo la comparto con los miembros de mi equipo. En estos casos, a menudo compartimos en formatos Swagger JSON o OpenAPI yaml, pero eso parece un poco anticuado.

Aquí Apidog es la herramienta perfecta de gestión de API que genera instantáneamente especificaciones de API altamente legibles basadas en datos Swagger JSON o YAML. También puedes compartir fácilmente esta especificación de API con la función de compartir API.

Apidog también proporciona varias funciones como herramienta de gestión del ciclo de vida de la API.

Diseño de API y generación de especificaciones: Apidog es la herramienta de diseño de API más fácil de usar, que te permite diseñar API de forma intuitiva sin código y generar cómodamente especificaciones OpenAPI y Swagger.

Gestión de API y pruebas unitarias: Apidog facilita mucho las pruebas unitarias, ya que puedes gestionar eficientemente tu API, enviar solicitudes de API y validar respuestas.

Automatización de pruebas de API: Apidog también admite pruebas automatizadas y está listo para CI/CD. Al utilizar esta función para establecer el número de hilos, etc., puedes implementar fácilmente pruebas de carga de API y automatización de pruebas de API.

Conclusión

En conclusión, Swagger-PHP es una herramienta poderosa para generar documentación Swagger para API basadas en PHP. Permite a los desarrolladores documentar fácilmente sus API y hacerlas accesibles a otros desarrolladores. Además, la integración de Swagger-UI con Swagger-php proporciona una interfaz fácil de usar para explorar y probar API.

Aquí hay algunos recursos para seguir aprendiendo sobre Swagger-PHP:

Documentación oficial: https://zircote.github.io/swagger-php/
Repositorio de GitHub: https://github.com/zircote/swagger-php
Swagger-ui: https://swagger.io/tools/swagger-ui/