Swagger 2 est mort, vive OpenAPI 3 - BreizhCamp 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 BREIZHCAMP 2018 mercredi 28 mars 2018 - Amphi C - 16h
2. About Grégory @gbloquel Doc by Fast Icon
3. About Sébastien @slecache Delorean by Fast Icon
4. Agenda ▪ OpenAPI ▪ Méthodologie ▪ Les APIs REST ▪ Nouveautés ▪ Démos ▪ Et après ?
5. Comment ? Ecrire une documentation pour les utilisateurs internes et externes, 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, 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, Self portrait in library by Nikolaos Haaponieni
8. 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
9. Qui a dit MS Word ? by Ryan McGuire
10. OpenAPI fka Swagger
11. OpenAPI Initiative (OAI) 2015 Démarrage OpenAPI Initiative Projet open source sous License Linux Fundation 2017 OpenAPI Spec 3.0.0 2010 Swagger 1.0 Création de la spécification par Wordnik 2014 Swagger 2.0
12. OpenAPI Initiative (OAI) https://www.openapis.org/membership/members
13. Qui est qui ? OpenAPI Initiative (OAI) = Regroupement d’acteurs OpenAPI Specification (OAS) = Spécification Swagger = Implémentation OpenAPI 3 = version 3 des spécifications
14. Méthodologie
15. Contract First Processus Itératif Definition Driven API Development by SmartBear
16. Rappel sur les APIs REST
17. 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
18. Les artefacts URI https://api.mycompany.com/v1/myresources/1337 Ressource myresources Représentation application/json {“id”: 1337, “name”: “1337 5|*34|<”}
19. Nouveautés de OAS 3.0.1 depuis Swagger 2.0
20. Nouveautés OpenAPI Spec 3 http://openapi-map.apihandyman.io/ A visual Guide to What’s New in Swagger 3 by readmeblog
21. Beaucoup de changements 1 nouveauté par slide 45 slides en 45 minutes ?
22. 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
23. Exemple Swagger 2.0 https://editor.swagger.io
24. 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”
25. Nouveautés Exemple version minimale
26. Nouveautés Exemple version minimale
27. Nouveautés servers - multiples urls host basePath schemes server
28. Nouveautés servers - variable templating host basePath schemes server
29. Nouveautés servers - dans les paths host basePath schemes server
30. Nouveautés servers - dans les paths host basePath schemes server
31. Nouveautés Sécurité ▪ Basic devient http ▪ Oauth2 updated ▪ Ajout de “scheme” et “bearer Format” ▪ Support d’OpenID Connect
32. Nouveautés Sécurité - OpenID Connect
33. Nouveautés Composants Déplacés -> definitions parameters responses components securityDefinitions
34. Nouveautés Composants Déplacés -> Renommés -> definitions parameters responses components securityDefinitions
35. Nouveautés Composants Déplacés -> Renommés -> Ajoutés -> definitions parameters responses components securityDefinitions
36. Modèles de données schemas definitions
37. Modèles de données schemas definitions
38. Nouveautés Format des requêtes Swagger 2.0 OpenAPI 3.0.1
39. Nouveautés Format des requêtes Swagger 2.0 OpenAPI 3.0.1
40. Nouveautés Format des requêtes Swagger 2.0 OpenAPI 3.0.1
41. Wildcards pour les codes
42. Content et media type
43. Polymorphisme avec OneOf
44. Composition avec AnyOf
45. Composition avec AnyOf
46. Composition avec AnyOf
47. Composition avec AnyOf
48. Composition avec AnyOf
49. Composition avec AnyOf
50. Composition avec AnyOf
51. Support des fichiers
52. Support des fichiers
53. Support des fichiers
54. Nouveautés Callback
55. Nouveautés Callback
56. Nouveautés Callback
57. Nouveautés Callback
58. Nouveautés Link - Pourquoi ? Définir une relation entre une réponse et autres opérations : “HATEOAS/Hypermedia” ▪ opérations possibles ▪ pagination (cursor)
59. Nouveautés Link - Exemple
60. Nouveautés Link - Exemple
61. Nouveautés Link - Exemple
62. Nouveautés Link - Exemple
63. Nouveautés Link - Exemple
64. On veut plus de code ! réutilisation de components
65. Démo ▪ Réutilisation de schema ▫ Collection paginée ▫ Item ▪ Factorisation ▫ Swagger 2 -> OAS3
66. Aller plus loin
67. Tooling ▪ Editeur: swagger-editor ▪ Génération code: swagger-codegen ▪ swagger-code-generators ▪ Changement du moteur de templating ▪ Java, JAXRS, HTML ▪ WIP PHP, Kotlin, Scala
68. Futur ▪ Prochaines fonctionnalités ? ▫ https://github.com/OAI/OpenAPI-Specification/issues/1466 ▪ Limitations ▫ Traits & resource types ▫ Templating des components
69. Back to the Future by Graffiti Life by MsSaraKelly under CC BY 2.0
70. Back to the Future by Graffiti Life by MsSaraKelly under CC BY 2.0
71. Questions ? @gbloquel & @slecache