Como crear un documento de OpenAPI(OAS) con Ruby on Rails y swagger-blocks
Cuando desarrollas una API siempre se busca la manera de exponer tus servicios para que el cliente que los utilice pueda entenderlos con una documentación clara; una buena forma de hacerlo es adoptando una especificación, en mi caso me ha servido adoptar OpenAPI.
Veremos un ejemplo rápido de como generar nuestro documento en formato OpenAPI utilizando la gema swagger-blocks.
Utilizaremos como ejemplo una API simple que implementa un CRUD de usuarios y documentaremos el método de obtener la información de un usuario por medio de su id.
Ruby versión 2.5.0, Ruby on Rails versión 5.1.5
rails new users-api-swagger-demo --api
cd users-api-swagger-demo
bundle
rails g scaffold User name:string email:string
rails db:migrateAgregamos la gema de swagger-blocks a nuestro Gemfile
gem 'swagger-blocks'El uso básico es incluir Swagger::Blocksen tu controller:
Creamos la configuración para poder crear nuestro documento tipo OpenAPI:
Agregamos la ruta que nos generará el archivo con formato OpenAPI:
resources :apidocs, only: [:index]Al ir a esa ruta (http://localhost:3000/apidocs) podemos ver el resultado en formato JSON.
Luego utilizando Swagger-UI podemos interactuar con el servicio que documentamos.
Al expandir el servicio que documentamos podemos interactuar con él, por ejemplo, obtener el usuario con el id = 1
Con esto terminamos un ejemplo muy simple, esperen una siguiente entrada con mas servicios y una “limpieza” a la parte de la documentación.
Les dejo un repo con el código:
