OpenAPI es un estándar para la de­s­cri­p­ción de las in­te­r­fa­ces de pro­gra­ma­ción, o ap­pli­ca­tion pro­gra­m­mi­ng in­te­r­fa­ces (API). La es­pe­ci­fi­ca­ción OpenAPI define un formato de de­s­cri­p­ción abierto e in­de­pe­n­die­n­te de los fa­bri­ca­n­tes para los servicios de API. En pa­r­ti­cu­lar, OpenAPI puede uti­li­zar­se para describir, de­sa­rro­llar, probar y do­cu­me­n­tar las API co­m­pa­ti­bles con REST.

La actual es­pe­ci­fi­ca­ción OpenAPI surgió del proyecto pre­de­ce­sor Swagger. La empresa de de­sa­rro­llo SmartBear sometió la es­pe­ci­fi­ca­ción existente de Swagger a una licencia abierta y dejó el ma­n­te­ni­mie­n­to y de­sa­rro­llo posterior en manos de la ini­cia­ti­va OpenAPI. Además de SmartBear, entre los miembros de la ini­cia­ti­va OpenAPI se en­cue­n­tran gigantes de la industria como Google, IBM y Microsoft. La Fundación Linux también apoya este proyecto.

API gratuita de IONOS
Gestione sus productos de Hosting a través de nuestra Interfaz de Pro­gra­ma­ción de Apli­ca­cio­nes (API)
  • Registros DNS
  • Ad­mi­ni­s­tra­ción SSL
  • Do­cu­me­n­ta­ción API

OpenAPI de un vistazo

Una cuestión que puede causar confusión es la di­s­ti­n­ción entre OpenAPI y Swagger. OpenAPI es una es­pe­ci­fi­ca­ción, es decir, una de­s­cri­p­ción abstracta que no está ligada a una apli­ca­ción técnica concreta. Hasta la versión 2.0, esta es­pe­ci­fi­ca­ción todavía se llamaba Swagger y luego fue re­no­m­bra­da como es­pe­ci­fi­ca­ción OpenAPI. Sin embargo, las he­rra­mie­n­tas pro­po­r­cio­na­das por SmartBear, la empresa que la de­sa­rro­lló ori­gi­na­l­me­n­te, siguen exi­s­tie­n­do con el nombre de Swagger.

Con OpenAPI, una API puede de­s­cri­bi­r­se de manera uniforme. Esto se conoce como “de­fi­ni­ción API” y se genera en un formato legible por máquina. En pa­r­ti­cu­lar, se utilizan dos lenguajes: YAML y JSON.

Nota

Aparte de la de­fi­ni­ción API, a veces se emplea el término “es­pe­ci­fi­ca­ción API”. Se trata de una de­s­cri­p­ción abstracta de una API creada ex­clu­si­va­me­n­te para el es­pe­c­ta­dor humano.

Té­c­ni­ca­me­n­te, YAML y JSON difieren solo li­ge­ra­me­n­te, por lo que es posible convertir au­to­má­ti­ca­me­n­te una de­fi­ni­ción API existente de un lenguaje a otro. Sin embargo, YAML tiene una es­tru­c­tu­ra más clara y es más fácil de leer para las personas. A co­n­ti­nua­ción, un ejemplo del mismo objeto del servidor OpenAPI, pre­se­n­ta­do en YAML y JSON:

# YAML
servers:
- url: https://development.example.com/v1
    description: Development server
- url: https://staging.example.com/v1
    description: Staging server
- url: https://api.example.com/v1
    description: Production server
// JSON
{
    "servers": [
        {
            "url": "https://development.example.com/v1",
            "description": "Development server"
        },
        {
            "url": "https://staging.example.com/v1",
            "description": "Staging server"
        },
        {
            "url": "https://api.example.com/v1",
            "description": "Production server"
        }
    ]
}

La es­pe­ci­fi­ca­ción OpenAPI define una serie de pro­pie­da­des que pueden uti­li­zar­se para de­sa­rro­llar una API propia. Estas pro­pie­da­des se agrupan en los llamados objetos (en inglés, objects). En la actual versión 3.0.3, OpenAPI define la es­tru­c­tu­ra de los si­guie­n­tes objetos, entre otros:

  • Info Object: versión, nombre, etc. de la API.
  • Contact Object: datos de contacto del proveedor de la API.
  • License Object: licencia bajo la cual la API pro­po­r­cio­na sus datos.
  • Server Object: nombres del host, es­tru­c­tu­ra del URL y puertos del servidor a través del cual se dirige la API.
  • Co­m­po­ne­nts Object: co­m­po­ne­n­tes en­ca­p­su­la­dos que pueden uti­li­zar­se varias veces dentro de una de­fi­ni­ción de API.
  • Paths Object: rutas relativas a los puntos finales de la API que se utilizan junto con el servidor del objeto.
  • Path Item Object: ope­ra­cio­nes pe­r­mi­ti­das para una ruta es­pe­cí­fi­ca como GET, PUT, POST, DELETE.
  • Operation Object: es­pe­ci­fi­ca, entre otras cosas, los pa­rá­me­tros y las re­s­pue­s­tas del servidor que se esperan de una operación.

¿Cuáles son las áreas de apli­ca­ción de OpenAPI?

En general, OpenAPI se utiliza para describir API REST de manera uniforme. Como esta de­s­cri­p­ción, es decir, la de­fi­ni­ción API, está di­s­po­ni­ble en un formato legible por máquina, se pueden generar au­to­má­ti­ca­me­n­te diversos ar­te­fa­c­tos virtuales a partir de ella. En concreto, estos incluyen:

  • Creación de do­cu­me­n­ta­ción API: La do­cu­me­n­ta­ción basada en HTML se genera au­to­má­ti­ca­me­n­te a partir de la de­fi­ni­ción API legible por máquina. Esta sirve como material de consulta para los de­sa­rro­lla­do­res que acceden a los servicios API. Si la de­fi­ni­ción API cambia, la do­cu­me­n­ta­ción se vuelve a generar para que ambas co­n­cue­r­den.
  • Creación de co­ne­xio­nes en di­fe­re­n­tes lenguajes de pro­gra­ma­ción: Con las he­rra­mie­n­tas apro­pia­das, se puede crear una bi­blio­te­ca de software adecuada del lado del cliente a partir de la de­fi­ni­ción API en un lenguaje de pro­gra­ma­ción co­m­pa­ti­ble. Esto permite a los pro­gra­ma­do­res de todo tipo acceder a la API. La bi­blio­te­ca de software se incorpora de manera co­n­ve­n­cio­nal. Por lo tanto, el acceso a los servicios de API tiene lugar, por ejemplo, mediante el acceso a las funciones dentro del mismo entorno de pro­gra­ma­ción.
  • Ela­bo­ra­ción de casos de prueba: Cada co­m­po­ne­n­te de un software debe someterse a diversas pruebas para asegurar su fu­n­cio­na­li­dad. En concreto, es preciso volver a probar un co­m­po­ne­n­te de software cada vez que se cambia el código su­b­ya­ce­n­te. A partir de la de­fi­ni­ción API, se pueden generar estos casos de prueba au­to­má­ti­ca­me­n­te para poder comprobar la fu­n­cio­na­li­dad de los co­m­po­ne­n­tes del software en todo momento.

En última instancia, cabe señalar que no todas las API pueden re­pre­se­n­tar­se uti­li­za­n­do OpenAPI. Sin embargo, las API REST son co­m­pa­ti­bles sin duda.

¿Qué ventajas tiene OpenAPI?

En general, la ventaja de OpenAPI es que la puesta en marcha, do­cu­me­n­ta­ción y prueba de una API son cohe­re­n­tes y co­n­s­ta­n­tes durante el de­sa­rro­llo y el ma­n­te­ni­mie­n­to. Además, el uso de la es­pe­ci­fi­ca­ción OpenAPI permite una mejor coor­di­na­ción del de­sa­rro­llo de la API entre los equipos de backend y frontend. En ambos equipos, los co­m­po­ne­n­tes del código pueden generarse a partir de la de­fi­ni­ción API para que tanto en backend como en frontend puedan de­sa­rro­llar­los y probarlos sin tener que esperar al otro.

Además de estas ventajas generales, OpenAPI se utiliza en pa­r­ti­cu­lar como estándar de base para el de­sa­rro­llo de API REST. Esto es atractivo, porque de­sa­rro­llar una API co­m­pa­ti­ble con REST de forma manual no es una tri­via­li­dad. Sin embargo, las API REST ofrecen algunas ventajas. Por ejemplo, REST se ejecuta sobre HTTP/S, y los puertos para ello están abiertos en cualquier co­r­ta­fue­gos.

Además, el uso de OpenAPI ofrece las si­guie­n­tes ventajas:

  • Definir las API HTTP in­de­pe­n­die­n­te­me­n­te de un lenguaje de pro­gra­ma­ción es­pe­cí­fi­co.
  • Generar código de servidor para una API definida en OpenAPI.
  • Generar bi­blio­te­cas del lado del cliente para una API co­m­pa­ti­ble con OpenAPI en más de 40 lenguajes de pro­gra­ma­ción.
  • Procesar una de­fi­ni­ción OpenAPI con las he­rra­mie­n­tas apro­pia­das.
  • Crear do­cu­me­n­ta­ción in­ter­ac­ti­va de API.
  • Permitir que las personas y las máquinas descubran y entiendan las ca­pa­ci­da­des de un servicio sin tener que mirar el código fuente o la do­cu­me­n­ta­ción adicional.
  • Acceder a los servicios de API con un gasto mínimo de puesta en marcha.

¿Qué versiones de OpenAPI están di­s­po­ni­bles y en qué se di­fe­re­n­cian?

En el momento de la redacción de este artículo, la versión 3.0.3 de OpenAPI es la más ac­tua­li­za­da. A co­n­ti­nua­ción, pre­se­n­ta­mos un breve resumen de las versiones an­te­rio­res:

Versión Nombre Estado
1.0, agosto de 2011 Es­pe­ci­fi­ca­ción Swagger No está en uso
2.0, se­p­tie­m­bre de 2014 Es­pe­ci­fi­ca­ción Swagger > es­pe­ci­fi­ca­ción OpenAPI Todavía en uso
3.0, julio de 2017 Es­pe­ci­fi­ca­ción OpenAPI Todavía en uso
Imagen: Versiones de OpenAPI: diferencias estructurales entre las versiones 2.0 y 3.0
En general, la es­tru­c­tu­ra de la es­pe­ci­fi­ca­ción OpenAPI se ha si­m­pli­fi­ca­do.

A co­n­ti­nua­ción, se exponen las novedades más im­po­r­ta­n­tes del cambio de la versión 2.0 a la 3.0:

Nuevo nombre del objeto raíz

Con el la­n­za­mie­n­to de la versión 3.0, se introdujo el objeto OpenAPI, que sustituye el objeto Swagger utilizado an­te­rio­r­me­n­te:

# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"

Múltiples hosts/se­r­vi­do­res

A partir de la versión 3.0 de OpenAPI, se puede acceder a una API desde más de un servidor. Además, es posible definir partes del URL del servidor de forma variable. A co­n­ti­nua­ción, mostramos un ejemplo:

"servers": [
        {
            "url": "https://{username}.example.com:{port}/{basePath}",
            "description": "The production API server",
            "variables": {
                "username": {
                    "default": "demo",
                    "description": "this value is assigned by the service provider, in this example `example.com`"
                },
                "port": {
                    "enum": [
                        "8443",
                        "443"
                    ],
                    "default": "8443"
                },
                "basePath": {
                    "default": "v2"
                }
            }
        }
    ]

Nuevos objetos co­m­po­ne­n­te y objetos re­fe­re­n­cia

Los objetos co­m­po­ne­n­te y objetos re­fe­re­n­cia añadidos en la versión 3.0 de OpenAPI son una de las pri­n­ci­pa­les novedades. El objeto co­m­po­ne­n­te permite definir múltiples objetos re­uti­li­za­bles dentro de la de­fi­ni­ción API. Los co­m­po­ne­n­tes de­no­mi­na­dos de esta manera se incluyen dentro de la de­fi­ni­ción API usando la es­tru­c­tu­ra especial $ref.

Mediante los co­m­po­ne­n­tes y re­fe­re­n­cias, es posible elaborar una de­fi­ni­ción API a partir de varias partes re­uti­li­za­bles. Esto facilita la lectura y reduce el tamaño de todo el documento. A co­n­ti­nua­ción, pre­se­n­ta­mos un ejemplo de la de­fi­ni­ción oficial de API de GitHub:

  1. Esquema de un re­po­si­to­rio de código GitHub, definido como un objeto co­m­po­ne­n­te.
  2. De­fi­ni­ción de licencia, referida a través de un co­m­po­ne­n­te definido ex­te­r­na­me­n­te.
"components": {
    "schemas": {
        // Esquema Repository
        "repository": {
            "title": "Repository",
            "description": "A git repository",
            "type": "object",
            "properties": {
                "id": {
                    "description": "Unique identifier of the repository",
                    "example": 42,
                    "type": "integer"
                },
                "node_id": {
                    "type": "string",
                    "example": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
                },
                "name": {
                    "description": "The name of the repository.",
                    "type": "string",
                    "example": "Team Environment"
                },
                "full_name": {
                    "type": "string",
                    "example": "octocat/Hello-World"
                },
                // Definición de licencia
                "license": {
                    "nullable": true,
                    "allOf": [
                        {
                            // Referencia a componente definido externamente
                            "$ref": "#/components/schemas/license-simple"
                        }
                    ]
                },

Uso de OpenAPI: dos ejemplos

La es­pe­ci­fi­ca­ción OpenAPI y sus he­rra­mie­n­tas co­rre­s­po­n­die­n­tes, en pa­r­ti­cu­lar Swagger, se utilizan con fre­cue­n­cia para crear diversas API. A co­n­ti­nua­ción, pre­se­n­ta­mos dos ejemplos:

API REST v3 de GitHub

El popular servicio de Git GitHub utiliza OpenAPI para describir su “API REST v3 de GitHub”. La de­fi­ni­ción de API está di­s­po­ni­ble en GitHub como un re­po­si­to­rio. Con su ayuda, un usuario puede de­te­r­mi­nar con exactitud a qué servicios se puede acceder a través de la API de GitHub y cómo deben es­tru­c­tu­rar­se exac­ta­me­n­te las so­li­ci­tu­des entrantes. Además, cua­l­quie­ra puede utilizar la API para generar el código adecuado uti­li­za­n­do las he­rra­mie­n­tas apro­pia­das.

Según GitHub, la de­fi­ni­ción API se utiliza para describir, crear, consumir y vi­sua­li­zar API REST. En el momento de redactar este artículo, la de­fi­ni­ción API no está completa. Por una parte, algunos en­ca­be­za­dos faltan aún y se añadirán en el futuro. También se observa que algunas de las posibles ope­ra­cio­nes de API pueden rea­li­zar­se a través de di­fe­re­n­tes rutas, aunque en la es­pe­ci­fi­ca­ción solo se incluye una ruta.

Por razones de co­m­pa­ti­bi­li­dad, GitHub ofrece la de­fi­ni­ción API en di­fe­re­n­tes formatos. Por un lado, hay una versión llamada “em­pa­que­ta­da” (bundled), que contiene los co­m­po­ne­n­tes in­tro­du­ci­dos con OpenAPI 3.0 y las re­fe­re­n­cias a los mismos. Como co­n­tra­pa­r­ti­da, se ofrece una versión de­no­mi­na­da “de­s­re­fe­re­n­cia­da” (de­re­fe­re­n­ced) en la que se resuelven todas las re­fe­re­n­cias. Debido a la re­du­n­da­n­cia que implica, la de­fi­ni­ción de API de­s­re­fe­re­n­cia­da es tres veces más grande que la em­pa­que­ta­da. Muchas he­rra­mie­n­tas no admiten todavía re­fe­re­n­cias. Para estos casos, la de­fi­ni­ción de API de­s­re­fe­re­n­cia­da es una buena opción.

Puedes echar un vistazo a la de­fi­ni­ción API tú mismo. Ten en cuenta que el archivo completo tiene un tamaño de varios megabytes. Para un archivo de texto, esta cantidad de in­fo­r­ma­ción es ex­tre­ma­da­me­n­te grande. GitHub no puede mostrar di­re­c­ta­me­n­te un archivo tan vo­lu­mi­no­so. Sin embargo, puedes utilizar el siguiente enlace para ver el GitHub API REST en el navegador. Esta es la versión en YAML, mucho más compacta y legible: GitHub API REST (YAML).

Ejemplo de una tienda de mascotas con Swa­g­ge­rHub

En segundo lugar, mostramos un ejemplo de API que puede crearse en Swa­g­ge­rHub. Swa­g­ge­rHub es una pla­ta­fo­r­ma online para diseñar y de­sa­rro­llar API REST con OpenAPI. Puedes crear una cuenta de usuario gratuita en esa pla­ta­fo­r­ma, aunque también puedes re­gi­s­trar­te con una cuenta existente en GitHub.

Una vez hayas accedido a Swa­g­ge­rHub, puedes crear una nueva API. Existe una opción que permite comenzar sobre una plantilla existente. Por ejemplo, hay una plantilla de API para una “Petstore” virtual, es decir, para una tienda de mascotas. La API de Petstore creada con la plantilla incluye una amplia gama de objetos OpenAPI. Entre otros, se en­cue­n­tran los si­guie­n­tes:

  • Datos de contacto, co­n­di­cio­nes de uso, licencia, etc.
  • Endpoints de API y las ope­ra­cio­nes de cada endpoint.
  • Pa­rá­me­tros de entrada y salida pe­r­mi­ti­dos de las ope­ra­cio­nes.
  • Es­pe­ci­fi­ca­cio­nes de seguridad.

Si observas la API de Petstore, puedes aprender mucho acerca de cómo funciona OpenAPI. Además, la de­fi­ni­ción de Petstore es un buen ejemplo de cómo de­sa­rro­llar una API de acuerdo con REST. Para finalizar, vamos a poner un ejemplo de código de la API de Petstore. Ana­li­za­mos la sección del código que aparece a co­n­ti­nua­ción:

  1. El código define el endpoint de API/pet.
  2. Con una solicitud HTTP POST, se añade una nueva mascota a la tienda de mascotas.
  3. Si, en su lugar, utilizas el verbo HTTP PUT en el mismo endpoint, puedes modificar una mascota existente.
  4. Se definen varias re­s­pue­s­tas del servidor para las ope­ra­cio­nes. En este ejemplo, los códigos de estado HTTP definidos para ello incluyen el conocido código de estado 404 “No en­co­n­tra­do”. En el caso de la API de Petstore, la expresión se tra­n­s­fo­r­ma en “Mascota no en­co­n­tra­da”.
Nota

Las líneas de código que comienzan con $ref y llevan el co­me­n­ta­rio de “OpenAPI 3.0+ Component” son re­fe­re­n­cias a co­m­po­ne­n­tes OpenAPI definidos in­di­vi­dua­l­me­n­te.

# Petstore API Template #
# API Endpoint '/pet'
/pet:
    # HTTP-POST Request
    post:
        tags:
            - pet
        summary: Add a new pet to the store
        operationId: addPet
        # HTTP-Status codes
        responses:
            '405':
                description: Invalid input
        security:
            # Permissions
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
        requestBody:
            # OpenAPI 3.0+ Component
            $ref: '#/components/requestBodies/Pet'
    # HTTP-PUT Request
    put:
        tags:
            - pet
        summary: Update an existing pet
        operationId: updatePet
        # HTTP-Status codes
        responses:
            '400':
                description: Invalid ID supplied
            '404':
                description: Pet not found
            '405':
                description: Validation exception
        security:
            # Permissions
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
        requestBody:
            # OpenAPI 3.0+ Component
            $ref: '#/components/requestBodies/Pet'
En resumen

OpenAPI se ha es­ta­ble­ci­do como un formato de de­s­cri­p­ción abierto e in­de­pe­n­die­n­te de los fa­bri­ca­n­tes para los servicios de API. Se espera que OpenAPI se utilice am­plia­me­n­te como estándar para el de­sa­rro­llo de API REST en un futuro próximo.

Ir al menú principal