api - example - ¿Cuál es el beneficio de usar Spring REST Docs en comparación con Swagger?
spring rest docs vs swagger (4)
Spring REST Docs fue lanzado recientemente y la documentación dice:
Este enfoque lo libera de las limitaciones impuestas por herramientas como Swagger
Entonces, quería preguntar cuándo es preferible usar Spring REST Docs en comparación con Swagger y qué limitaciones libera.
Acabo de ver una presentación aquí que toca su pregunta entre otros temas:
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger no admite hipermedia en absoluto / está centrado en URI
El método de Swagger para inspeccionar su código puede retrasarse con respecto a su código. Es posible realizar un cambio en su código que Swagger no comprenda y no procese correctamente hasta que Swagger se actualice.
Swagger requiere muchas anotaciones, y es doloroso incluir el texto descriptivo que desea en un documento API en las anotaciones.
Hay algunas cosas que Swagger no puede resolver al inspeccionar su código.
En cualquier caso, estos son solo un par de puntos. El presentador hace un trabajo mucho mejor discutiéndolo de lo que yo podría.
De los documentos de REST de primavera :
El objetivo de Spring REST Docs es ayudarlo a producir documentación para sus servicios RESTful que sea precisa y legible
Este enfoque basado en pruebas ayuda a garantizar la precisión de la documentación de su servicio. Si un fragmento es incorrecto, la prueba que lo produce fallará.
Ventajas de los documentos de REST de primavera:
- La documentación está escrita en el código de prueba para que no sobrecargue el código principal con muchas anotaciones y descripciones.
- Los documentos y ejemplos generados son precisos porque la prueba relacionada debe pasar
- Los documentos pueden proporcionar fragmentos más específicos y descriptivos.
- El formato es adecuado para la publicación.
Desventajas de los documentos de REST de primavera:
- Requiere mas trabajo
- La documentación proporciona ejemplos de solicitud / respuesta, pero no proporciona herramientas interactivas para modificar y probar solicitudes
Ventajas de Swagger:
- Generación rápida y automatizada desde un código.
- Ejecución interactiva de solicitudes - se puede usar para pruebas de aceptación
- Construido alrededor de la especificación de OpenAPI
Desventajas Swagger:
- Para documentación más descriptiva se requerirán muchas anotaciones.
- Las pruebas no están relacionadas con la documentación, por lo que a veces la documentación puede desviarse de la realidad.
Hay alguna limitación con Swagger y la pila de muelles específica.
Por ejemplo: con "param" en su Mapeo de Solicitud, puede definir más de un método con la misma url y así simplificar su código. Pero swagger te muestra un solo método.
Pensé que me gustaría dar un poco más de contexto sobre Swagger, qué es y qué no. Creo que esto podría ayudar a responder a su pregunta.
Swagger 2.0 está siendo adoptado por una gran cantidad de grandes nombres y grandes plataformas como Microsoft Azure, Paypal, SwaggerHub.com, DynamicApis.com, etc ... Algo a tener en cuenta es que Swagger es muy simplemente una especificación . No es un marco. Hay muchos frameworks creados para generar resultados de Swagger que se arrastran a través de su código mirando la información de su API para generar el archivo Jagger de Swagger 2.0 que representa su API. La interfaz de usuario de Swagger en la que ves tus API se maneja directamente desde este archivo JSON de Swagger 2.0. el violinista lo revisa
Es importante tener en cuenta que un marco que se creó para permitirle "usar Swagger" no es la forma en que Swagger tiene que trabajar (es decir, depende completamente de la implementación del marco de terceros). Si el marco que está utilizando para generar sus documentos Swagger 2.0 y la interfaz de usuario no está funcionando para usted, debería poder encontrar otro marco que genere los artefactos de Swagger e intercambiar las tecnologías.
Espero que esto ayude.