Como convertirse en un experto en Swagger

Transcript

1. Como convertirse en un
   experto en Swagger
   Lautaro Carro
   Organizador de Latino .NET Online
   

   View Slide

2. Las API son la manera más popular
   de comunicar 2 o más aplicaciones
   distintas y es de gran importancia
   tener una buena documentación de
   la misma.
   

   View Slide

3. Swagger es elegida por millones de
   desarrolladores en el mundo por más
   de 10 años.
   Hoy en día es indispensable en
   nuestras APIS.
   

   View Slide

4. View Slide

5. View Slide

6. Niveles de Conocimiento
   Junior
   Semi-
   Senior
   Senior
   

   View Slide

7. Niveles de Conocimiento
   Junior
   • ¿Qué es Swagger?
   • ¿Qué es OpenApi?
   • Instalación
   Semi-Senior
   • Configuración
   • Personalizar
   SwaggerUI
   • Seguridad
   • Generación de
   código
   Senior
   • Swagger en
   Producción
   • Generación de
   Test Cases
   • Api First
   • Alternativas
   

   View Slide

8. View Slide

9. Swagger
    Swagger es un conjunto de herramientas de software de código abierto para
   diseñar, construir, documentar y utilizar servicios REST.
   

   View Slide

10. Swagger
     Swagger es un conjunto de herramientas de software de código abierto para
    diseñar, construir, documentar y utilizar servicios REST.
     Documentación Automatizada
     Generación de Código
     Generación de Casos de Prueba
    

    View Slide

11. Documento Swagger
    

    View Slide

12. Documento Swagger
    

    View Slide

13. Historia
    20
    11
    CREACIÓN SMARTBEAR OPENAPI
    Tony Tam diseñó una
    representación JSON simple de
    la API, basándose en la
    flexibilidad del estilo de
    arquitectura REST
    Anunció que estaba ayudando a
    crear una nueva organización,
    bajo el patrocinio de la
    Fundación Linux
    La especificación Swagger pasó a
    llamarse Especificación OpenAPI.
    OpenApi hoy es Open Source.
    20
    15
    20
    16
    

    View Slide

14. OpenApi
    Info: versión, nombre, etc. de la API.
    Contact: datos de contacto del proveedor de la
    API.
    License: licencia bajo la cual la API proporciona
    sus datos.
    Server: nombres del host, estructura del URL y
    puertos del servidor a través del cual se dirige la
    API.
    

    View Slide

15. OpenApi
    Paths: rutas relativas a los puntos finales de la
    API que se utilizan junto con el servidor del
    objeto.
    Path Item: operaciones permitidas para una ruta
    específica como GET, PUT, POST, DELETE.
    Components: componentes encapsulados que
    pueden utilizarse varias veces dentro de una
    definición de API.
    Operation: especifica, entre otras cosas, los
    parámetros y las respuestas del servidor que se
    esperan de una operación.
    

    View Slide

16. Swagger en nuestras WebApis
    

    View Slide

17. View Slide

18. Esquemas de Seguridad
     SwaggerUI nos permite autorizarnos mediante los esquemas de seguridad
    Basic, Bearer y/o OAuth).
     Si nuestra API maneja políticas de autorización, es obligatorio que SwaggerUI
    me permita ingresar credenciales o un token.
    

    View Slide

19. View Slide

20. Generación de Código
    

    View Slide

21. Generación de Código
    https://openapi-generator.tech/
    csharp
    

    View Slide

22. View Slide

23. Swagger en Producción
     ¿Cómo se debe usar Swagger en Producción?
    

    View Slide

24. View Slide

25. Swagger en Producción (excepciones)
    

    View Slide

26. El enfoque API First
    El enfoque API First implica tener a las APIS como el primer y principal elemento
    de su estrategia de productos y servicios.
    API First asume que el diseño y el desarrollo de una API son anteriores a su
    implementación.
    Se diseña, se mockea, se desarrolla y se documenta de forma colaborativa antes
    que las aplicaciones o servicios clientes sean desarrollados.
    

    View Slide

27. El enfoque API First
    

    View Slide

28. El enfoque API First
     Utilizando OpenApi podrás diseñar los contractos de las APIS para que sean
    consistentes y reusables. Antes de comenzar con el código.
     Enfoque muy popular en Microservicios.
     Permite a equipos de desarrollo trabajar en paralelo
     Reduce los costos de desarrollos
     Aumenta la velocidad de comercialización
     Reduce los riesgos de fallo
     Asegura una buena experiencia de desarrollo
    

    View Slide

29. Generación de Casos de Prueba:
    Swagger Inspector
     Es una aplicación web que sirve para realizar request a los endpoints
    definidos en el documento de OpenApi.
    https://inspector.swagger.io/
    

    View Slide

30. Generación de Casos de Prueba:
    Postman
     Nos permite importar un archivo OpenApi y nos genera todas las request.
    Nosotros solo debemos codear los test para que se ejecuten
    automáticamente.
    

    View Slide

31. Alternativa a SwaggerUI
    https://github.com/Redocly/redoc
    

    View Slide

32. Conclusiones
     Swagger es un conjunto de herramientas para generar y leer documentos con
    la especificación OpenApi
     Existen muchas herramientas hechas por SmartBear y por otras organizaciones
    para trabajar con documentos OpenApi
     La librería Swashbuckle.AspNetCore provee una gran cantidad de métodos
    para configurar Swagger y personalizar SwaggerUI
     Usar OpenApi mejora considerablemente la experiencia de Desarrollo y de
    Testing
    

    View Slide

33. Muchas Gracias!
    Como convertirse en un experto en Swagger
    Lautaro Carro (@lauchacarro)
    

    View Slide