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

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.

B02669cd04301a651a15322340fc9991?s=128

Sébastien LECACHEUR

March 28, 2018
Tweet

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