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

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.

B02669cd04301a651a15322340fc9991?s=128

Sébastien LECACHEUR

April 20, 2018
Tweet

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