Como crear un documento de OpenAPI(OAS) con Ruby on Rails y swagger-blocks — Parte dos
Como lo prometí, les tengo la segunda parte de la implementación de OAS en Rails. Si te perdiste la primera parte, te dejo el link:
Para comenzar haremos un tipo de “limpieza” a nuestro código, moveremos la parte que tenemos en el controlador(users_controller.rb) a un archivo dentro de la carpeta de concerns (app/controllers/concerns/swagger/users_api.rb
Ahora removeremos este código de nuestro controlador e incluiremos la referencia a este módulo.
Ahora vamos a crear un archivo para documentar la respuesta que damos del usuario, en este caso lo incluiremos en los concerns de la parte de los modelos.
Removemos la parte del schema User del response que esta en el archivo de app/controllers/concerns/swagger/users_api.rb y creamos el archivo app/models/concerns/swagger/user_schema.rb, para finalizar incluimos la clase User dentro del array SWAGGERED_CLASSES que se encuentra dentro del archivo app/controllers/apidocs_controller.rb.
Con esto ya tenemos nuestros modelos y controladores solo incluyendo los módulos que creamos, así es menos confuso porque hay menos código.
Ya teniendo esto, implementamos los endpoints que nos faltan, los cambios que veremos es que en el mismo swagger path podemos incluir mas de una operación(get, put, delete, etc.); también incluimos un tag para poder agrupar todos los endpoints que pertenecen a los usuarios y finalmente mover el parámetro user_id que tenemos en el path fuera del operation y al inicio del swagger_path para que todas las operaciones dentro de ese path lo incluyan.
El modulo de users_api al final quedaría así con todos los endpoints documentados:
Les recuerdo que descarguen Swagger-UI para que puedan visualizar y probar sus endpoints desde su navegador.
Dejo de nuevo el link al repositorio con el código en el branch para este post.
