Que es esto que me enviaron cuando pedi documentacion de una API?!?

Te han pedido incorporar una API de terceros en tu aplicacion y cuando pedis la documentacion, te envian un archivo json o una url indicandote que alli esta la especificacion OpenAPI (o la documentacion Swagger) …

Y ahora? Esto como se come?

Bien, la especificacion OpenAPI (anteriormente conocida como especificacion Swagger) es un formato para describir APIs REST. Podes encontrar mas info sobre OpenAPI en el sitio oficial (en ingles)

Supongamos que queremos integrar una API que nos da acceso a la biblia a nuestra aplicacion, y nos indican que la documentacion se encuentra en https://api.scripture.api.bible/v1/swagger.json

Si intentamos acceder en nuestro navegador, veremos el contenido del archivo json, con gran cantidad de informacion

Una mejor forma de acceder, es utilizando el editor que OpenAPI nos provee, el mismo se encuentra en https://editor.swagger.io/ y veremos en primer lugar una documentacion de ejemplo de la API Petstore

Para cargar nuestra documentacion de biblia, debemos utilizar el menu File -> Import URL y alli pegar la URL de la documentacion

Veremos a nuestra izquierda, el archivo json formateado y a la derecha paneles que nos permitiran interactuar con las distintas direcciones que provee la API

Podemos acceder a detalles de una direccion en particular

Y utilizando el boton Try it out, podemos ejecutar llamadas de prueba, ver parametros de entrada y ejemplos de salida.

En el caso de esta API de biblia, antes de poder hacer llamadas tenemos que tener acceso a un token de autorizacion, el mismo se carga en la opcion Authorize, otras APIs pueden tener distintas implementaciones de seguridad, por lo que la informacion a ingresar aqui depende de cada caso.

Espero que este breve tutorial les haya sido de utilidad y les sirva como punto de entrada para comenzar a utilizar swagger de forma mas sencilla y eficiente

Nos leemos!