Swagger 2 est mort, vive OpenAPI 3 - Devoxx France 2018 - Conférence

La version 3 d'OpenAPI Spec (fka Swagger) représente l'âge de la maturité pour cette solution de spécification d'API RESTful. La réutilisation est enfin possible : Don't Repeat Your Self !

Nous verrons donc comment décrire très simplement et rapidement une API et factoriser sa description.

Transcript

1. Swagger 2 est mort, vive OpenAPI 3 Grégory BLOQUEL @gbloquel Sébastien LECACHEUR @slecache Devoxx France vendredi 20 avril 2018 - Amphi Bleu - 13h55
2. About Grégory @gbloquel Doc by Fast Icon
3. About Sébastien @slecache Delorean by Fast Icon
4. Comment ? Ecrire une documentation pour les utilisateurs internes et externes, Self portrait in library by Nikolaos Haaponieni
5. Comment ? Ecrire une documentation pour les utilisateurs internes et externes, Rédigée avant l’implémentation pour une approche Contract First, Self portrait in library by Nikolaos Haaponieni
6. Comment ? Ecrire une documentation pour les utilisateurs internes et externes, Rédigée avant l’implémentation pour une approche Contract First, gérée comme du code source, Self portrait in library by Nikolaos Haaponieni
7. Comment ? Ecrire une documentation pour les utilisateurs internes et externes, Rédigée avant l’implémentation pour une approche Contract First, gérée comme du code source, et lisible par des humains. Self portrait in library by Nikolaos Haaponieni
8. Qui a dit MS Word ? by Ryan McGuire
9. OpenAPI fka Swagger
10. OpenAPI Initiative (OAI) 2015 Démarrage OpenAPI Initiative Projet open source intégrant Linux Fundation 2017 OpenAPI Spec 3.0.0 2010 Swagger 1.0 Création de la spécification par Wordnik 2014 Swagger 2.0
11. OpenAPI Initiative (OAI) https://www.openapis.org/membership/members
12. Qui est qui ? OpenAPI Initiative (OAI) = Regroupement d’acteurs OpenAPI Specification (OAS) = Spécification Swagger = Implémentation OpenAPI 3 = version 3 des spécifications
13. Méthodologie
14. Contract First Processus Itératif Definition Driven API Development by SmartBear
15. Rappel sur les APIs REST
16. Terminologie URI comme identifiant de ressource Verbe comme identifiant d’opération Réponse HTTP comme représentation de la ressource Liens comme relation entre les ressources
17. Les artefacts URI https://api.mycompany.com/v1/myresources/1337 Ressource myresources Représentation application/json {“id”: 1337, “name”: “1337 5|*34|<”}
18. Nouveautés de OAS 3.0.1 depuis Swagger 2.0
19. Nouveautés OpenAPI Spec 3 http://openapi-map.apihandyman.io/ A visual Guide to What’s New in Swagger 3 by readmeblog
20. Beaucoup de changements 1 nouveauté par slide 45 slides en 45 minutes ?
21. Beaucoup de changements 1 nouveauté par slide 45 slides en 45 minutes ? 1 nouveauté par slide 45 slides en 45 minutes ? Non ! Allons à l’essentiel ! by Ryan McGuire
22. Exemple Swagger 2.0 https://editor.swagger.io
23. Nouveautés Format ▪ GFM vers Common Mark ▪ Gestion des versions en SEMVER ▪ JSON Schema Wright Draft 00 ▫ de nouveaux types supportés “oneOf, anyOf, not, nullable, writeOnly”
24. Nouveautés Exemple version minimale
25. Nouveautés Exemple version minimale
26. Nouveautés servers host basePath schemes server
27. Nouveautés servers host basePath schemes server
28. Nouveautés servers host basePath schemes server
29. Nouveautés servers host basePath schemes server
30. Nouveautés Sécurité ▪ Basic devient http ▪ Oauth2 updated ▪ Ajout de “scheme” et “bearer Format” ▪ Support d’OpenID Connect
31. Nouveautés Composants definitions parameters responses components securityDefinitions
32. Nouveautés Composants Déplacés -> definitions parameters responses components securityDefinitions
33. Nouveautés Composants Déplacés -> Renommés -> definitions parameters responses components securityDefinitions
34. Nouveautés Composants Déplacés -> Renommés -> Ajoutés -> definitions parameters responses components securityDefinitions
35. Nouveautés Format des requêtes Swagger 2.0 OpenAPI 3.0.1
36. Nouveautés Format des requêtes Swagger 2.0 OpenAPI 3.0.1
37. Nouveautés Format des requêtes Swagger 2.0 OpenAPI 3.0.1
38. Wildcards pour les codes
39. Content et media type
40. oneOf/anyOf Polymorphisme/Composition
41. Nouveautés Callback
42. Nouveautés Callback
43. Nouveautés Callback
44. Nouveautés Callback
45. Nouveautés Link - Pourquoi ? Définir une relation entre une réponse et d’autres opérations : “HATEOAS/Hypermedia” ▪ opérations possibles ▪ pagination (cursor)
46. Nouveautés Link - Exemple
47. Nouveautés Link - Exemple
48. Nouveautés Link - Exemple
49. Nouveautés Link - Exemple
50. Nouveautés Link - Exemple
51. On veut plus de code ! réutilisation de components
52. Démo ▪ Factorisation ▫ Swagger 2 -> OAS3
53. Aller plus loin
54. Tooling ▪ Editeur: swagger-editor ▪ Génération code: swagger-codegen ▪ swagger-code-generators ▪ Changement du moteur de templating ▪ Java, JAXRS, Kotlin, HTML ▪ WIP PHP, Scala
55. Futur ▪ Prochaines fonctionnalités ? ▫ https://github.com/OAI/OpenAPI-Specification/issues/1466 ▪ Limitations ▫ Traits & resource types ▫ Templating des components
56. by Ryan McGuire
57. Software is eating the world Marc Andreessen / WSJ August 2011 by Ryan McGuire
58. APIs are eating Software API Days SF 2013 by Ryan McGuire
59. by Ryan McGuire Be the King of APIs with docs!
60. by Ryan McGuire
61. Questions ? @gbloquel & @slecache