OpenAPI
Proporciona documentos de especificación OpenAPI (Swagger) que describen las APIs REST de Drupal.
openapi
Install
composer require 'drupal/openapi:8.x-2.3'
composer require 'drupal/openapi:8.x-2.1'
Overview
El módulo OpenAPI genera documentación de API legible por máquinas siguiendo el estándar de especificación OpenAPI (anteriormente Swagger). Esto permite la generación automática de documentación de API, generación de código cliente y capacidades de prueba de API para sitios Drupal.
Este es un módulo fundamental que proporciona el framework central y el sistema de plugins para generar especificaciones OpenAPI. Para usarlo, debes instalar módulos de integración como OpenAPI REST para el módulo REST del Core de Drupal o OpenAPI JSON:API para el módulo JSON:API.
Las especificaciones OpenAPI generadas pueden usarse con herramientas como Swagger Editor, Swagger Codegen, Postman y varios visualizadores de documentación de API. El módulo también se integra con el módulo OpenAPI UI para proporcionar visualización de documentación en el navegador usando herramientas como ReDoc o Swagger UI.
Features
- Genera documentos de especificación OpenAPI 2.0 (Swagger) en formato JSON para APIs REST de Drupal
- Arquitectura basada en plugins que permite a otros módulos proporcionar generadores de documentación de API para diferentes implementaciones de API
- Soporte integrado para múltiples métodos de autenticación incluyendo Basic Auth, OAuth2 y autenticación por Token CSRF
- Interfaz de administración que lista todos los generadores de API disponibles con enlaces para descargar especificaciones o explorar documentación
- Integración con el módulo OpenAPI UI para visualización interactiva de documentación de API dentro de Drupal
- Opciones de filtrado para generar especificaciones para tipos de entidad o bundles específicos
- Detección automática de definiciones de seguridad basada en los proveedores de autenticación habilitados
- Utilidades de validación y limpieza de esquemas para especificaciones generadas
Use Cases
Generar documentación de API para desarrolladores
Usa OpenAPI para generar documentación completa de API REST para tu sitio Drupal. Después de instalar el módulo con un módulo de integración (openapi_rest u openapi_jsonapi), los desarrolladores pueden acceder a /openapi/rest?_format=json o /openapi/jsonapi?_format=json para descargar la especificación completa de la API. Este archivo JSON puede importarse en herramientas como Swagger Editor para navegación interactiva o Swagger Codegen para generar bibliotecas cliente en varios lenguajes de programación.
Explorador interactivo de API
Combina OpenAPI con los módulos OpenAPI UI y openapi_ui_redoc para proporcionar una interfaz de documentación de API en el navegador. Navega a /admin/config/services/openapi/redoc/rest o /admin/config/services/openapi/redoc/jsonapi para explorar tu API interactivamente. Los desarrolladores pueden ver todos los endpoints disponibles, esquemas de solicitud/respuesta y requisitos de autenticación sin salir del navegador.
Generación de código cliente de API
Descarga la especificación OpenAPI y usa Swagger Codegen u OpenAPI Generator para crear automáticamente bibliotecas cliente para tu API Drupal en lenguajes como JavaScript, Python, PHP, Java y muchos otros. Esto asegura un consumo de API con tipos seguros y reduce el tiempo de desarrollo para aplicaciones que se integran con tu sitio Drupal.
Documentación específica por entidad
Genera documentación para tipos de entidad o bundles específicos pasando opciones en la URL. Por ejemplo, /openapi/rest?_format=json&options[entity_type_id]=node&options[bundle_name]=article genera documentación solo para nodos de tipo artículo. Esto es útil al crear documentación enfocada para consumidores específicos de API.
Pruebas de API con Postman
Importa la especificación OpenAPI generada en Postman o herramientas similares de prueba de API. La especificación incluye URLs de endpoints, requisitos de autenticación, parámetros de solicitud y respuestas esperadas, facilitando la creación de colecciones de prueba y la validación del comportamiento de la API.
Generador de documentación de API personalizado
Crea un plugin generador OpenAPI personalizado para un módulo de API personalizado o una implementación de API única. Extiende OpenApiGeneratorBase e implementa métodos como getPaths(), getDefinitions(), getTags() y getApiName() para generar especificaciones que coincidan con la estructura de tu API. Coloca el plugin en el directorio src/Plugin/openapi/OpenApiGenerator de tu módulo con la anotación @OpenApiGenerator.
Tips
- Usa el módulo openapi_ui_redoc para una interfaz de documentación limpia y responsive que funciona bien tanto para desarrolladores como para interesados
- Filtra especificaciones de API grandes usando opciones de URL como entity_type_id y bundle_name para generar documentación enfocada para casos de uso específicos
- Guarda en marcadores la URL de descarga directa de JSON (/openapi/rest?_format=json) para acceso rápido durante el desarrollo
- La especificación generada incluye información de scheme (http/https), host y basePath detectada automáticamente de la configuración de tu sitio
- Las definiciones de seguridad se completan automáticamente basándose en los módulos de autenticación habilitados - habilita basic_auth o Simple OAuth para incluir esos métodos de autenticación
- Los generadores personalizados pueden usar la opción 'exclude' para filtrar tipos de entidad o bundles específicos de la especificación
Technical Details
Admin Pages 1
/admin/config/services/openapi
La página principal de administración de OpenAPI que lista todos los generadores de documentación de API disponibles. Esta página proporciona una visión general de la funcionalidad de OpenAPI y enlaces para descargar especificaciones o ver documentación interactiva.
Permissions 1
Hooks 1
hook_openapi_generator_alter
Permite a los módulos alterar las definiciones de plugins generadores OpenAPI. Se llama durante el descubrimiento de plugins para modificar los generadores disponibles.
Troubleshooting 5
Instala un módulo de integración que proporcione plugins generadores. Para Core REST, instala openapi_rest. Para JSON:API, instala openapi_jsonapi. Sin estos módulos de integración, el módulo OpenAPI no tiene APIs que documentar.
Asegúrate de que el usuario tenga el permiso 'access openapi api docs'. Este permiso es requerido para ver la página de administración de OpenAPI y descargar especificaciones.
Asegúrate de que el módulo de API correspondiente (REST o JSON:API) esté habilitado y tenga recursos configurados. Para REST, habilita y configura recursos REST en /admin/config/services/rest. Para JSON:API, asegúrate de que los tipos de entidad estén habilitados para acceso JSON:API.
Instala el módulo openapi_ui junto con un módulo de biblioteca UI como openapi_ui_redoc u openapi_ui_swagger_ui. Sin estos módulos, solo estará disponible el enlace de descarga de especificación.
El módulo detecta automáticamente los proveedores de autenticación registrados con Drupal. Asegúrate de que módulos como basic_auth, oauth2 (Simple OAuth) u otros módulos de autenticación estén correctamente habilitados y configurados.
Security Notes 3
- El permiso 'access openapi api docs' controla el acceso a la documentación de API. Considera cuidadosamente quién debe tener este permiso, ya que la documentación de API puede revelar la estructura de los datos de tu sitio
- Las especificaciones de API se generan basándose en los permisos del usuario actual y pueden incluir endpoints que el usuario puede ver pero no necesariamente acceder
- Ten cuidado al exponer documentación OpenAPI públicamente, ya que proporciona información detallada sobre la estructura de API de tu sitio que podría usarse para reconocimiento