Le document présente la validation des contrats d'interfaces au format OpenAPI et les outils associés comme Swagger, permettant une documentation et des tests d'API simplifiés. Il discute des méthodologies 'contract first' et 'contract last', ainsi que des enjeux architecturaux récents, notamment l'importance de la validation des évolutions dans une suite distribuée. Enfin, il introduit Wakeonweb/Swagger, un composant PHP pour faciliter l'intégration et la validation des APIs selon ces spécifications.

1. La validation des contrats
d’interfaces au format OpenAPI
Meetup - 16 Mai 2017
Marseille PHP User Group - AFUP
Nicolas Macherey – Fondateur WakeOnWeb

2. OpenAPI/Swagger: Qu’est-ce que c’est ?
• Un format simple, compréhensible et collaboratif
• Complet, très répandu
• YAML ou JSON
• Structuré et respectant l’HTTP
• Facile à intégrer au SCM (Git ou autre)
• Permet de sortir une doc simple et compréhensible
• Des outils dédiés
• Swagger Editor: Editeur web avancé avec système de validation
• Swagger UI: Générateur de documentation à partir de la spec
• Swagger CodeGen: Générateur de code client/serveur
Swagger UI permet aussi de tester les APIs manuellement en
faisant des appels depuis l’interface exposant la documentation.
http://swagger.io/
swagger: '2.0’
info:
version: "1.0.0"
title: Basic Auth Example
description: |
An example for how to use Basic Auth with Swagger.
**User Name and Password**
* User Name: `user`
* Password: `pass`
host: basic-auth-server.herokuapp.com
schemes:
- http
- https
securityDefinitions:
basicAuth:
type: basic
description: HTTP Basic Authentication….
paths:
/:
get:
security:
- basicAuth: []
responses:
200:
description: Will send `Authenticated`…

3. Méthodologies: Contract First/Last mais pourquoi ?
Contract Last
Les spécifications d’API sont extraites du code comme un
constat de ce qui a été fait…
• Agile/Plus rapide
• Moins collaboratif Très difficile de paralléliser le travail
• Correspond toujours à la réalité de l’API
Contract First
Les spécifications sont le cœur central du développement
elles sont faites au moment des phases de spécifications
• Facilite le travail parallèle (Gain de productivité)
• Moins agile, nécessite la mise en place de
communications dédiées
• Peut contenir des différences à l’implémentation
(Recette)
• Permet la génération automatique de code serveur

4. Les enjeux architecturaux récents…
• Propriétés
• Chaque service peut être (et est) conçu, développé, testé et déployé
indépendamment.
• De ce fait, il peut évoluer a son rythme.
• Bénéficie d’une forte cohésion interne à l’application.
• Est parfaitement adapté aux technologies de type docker, permettant
de déployer chaque service dans un conteneur dédié.
• Avantages
• Réduction du Time To Market, notamment en parallélisant les
développements
• Flexibilité technologique et indépendance pour chaque service
• Extensibilité / Evolutivité largement facilité
• Résilience augmentée
• Réduction des coûts de maintenance et d’évolution
• Réduction des risques
Mais il y a tout de même des règles à respecter pour que cela se
passe bien…
API GATEWAY

5. L’importance de valider que les nouvelles évolutions
respectent les contrats d’interface dans une suite distribuée
(entrée/sortie)
Intégration aux tests automatisés
Intégration continue
Non-Régression
Objectif n°1: Mieux gérer ses évolutions

6. Identifier les erreurs
Sécuriser ses API
Faciliter ses traitements métiers
Intégration aux frameworks
Intégration en production
Objectif n°2: Faciliter le traitement des requêtes HTTP

7. WakeOnWeb/swagger: Présentation
▪ Répondre à un besoin (d’abord perso...)
▪ L’existant n’était pas satisfaisant
▪ Faciliter nos phases d’intégrations front/back ou dans nos suites de services
▪ Une première ouverture vers l’OpenSource/Contribution communautaire
▪ Un composant utilisable au sein de tous les frameworks PHP (Silex, Laravel, Symfony…)
▪ Extensible et rapide
▪ Compatible avec différents validateurs de données JSON (JustinRainbow/Jval…)

8. WakeOnWeb/swagger: Fonctionnalités
▪ Ajout de validateurs personnalisés
▪ Compatibilité PSR-7 (MessageInterface)
▪ Compatibilité PSR-6 (Cache)
▪ Respect de la spécification OpenAPI au format Swagger 2.0 (3.0 à venir)
▪ Gestion des extensions vendor spécifiques
▪ Intégration PHPUnit/Behat
▪ Intégration Symfony

9. WakeOnWeb/swagger: Installation
> composer require wakeonweb/swagger
> composer require justinrainbow/json-schema
Le composant intègre 1 bridge et permet d’en intégrer
d’autres

10. // File system for cache storage
$filesystem = new Filesystem(new Local('path/to/wakeonweb/swagger'));
$factory = new SwaggerFactory(new FilesystemCachePool($filesystem));
// Add loader Yaml and JSON supported
$factory->addLoader(new YamlLoader());
// Parse file and store to cache directory and/or read the file content
$swagger = $factory->buildFrom('path/to/swagger.yml');
$this->swaggerValidator = new SwaggerValidator($swagger);
// Register the appropriate JSON Schema Validator for Content validation
$this->swaggerValidator->registerContentValidator(new JustinRainbowJsonSchemaValidator());
// Converts the response to a PRS-7 compliant format.
$response = (new DiactorosFactory())->createResponse($response);
// Validate the response for the given path/method/status
$this->swaggerValidator->validateResponseFor(
$response,
PathItem::METHOD_GET, '/api/users/{id}/orders', 200
);
WakeOnWeb/swagger: Utilisation

11. WakeOnWeb/swagger: Exemple d’intégration a Behat
class OpenApiValidationContext implements Context, SnippetAcceptingContext
{
use KernelDictionary;
private $swaggerValidator;
/**
* @BeforeScenario
*/
public function loadSwaggerValidator()
{
$kernel = $this->getContainer()->get('kernel');
$filesystem = new Filesystem(new Local($kernel->getCacheDir() . '/wakeonweb/swagger'));
$factory = new SwaggerFactory(new FilesystemCachePool($filesystem));
$factory->addLoader(new YamlLoader());
$swagger = $factory->buildFrom($kernel->getRootDir() . '/../docs/api/swagger.yml');
$this->swaggerValidator = new SwaggerValidator($swagger);
$this->swaggerValidator->registerContentValidator(new JustinRainbowJsonSchemaValidator());
}
/**
* @Then The response should validate :path open api specification with :method method and :statusCode status
*/
public function validateOpenApiSpecification($path, $method = PathItem::METHOD_GET, $statusCode = 200)
{
$this->swaggerValidator->validateResponseFor(
(new DiactorosFactory())->createResponse($this->response), $method, $path, $statusCode);
}
}

12. WakeOnWeb/swagger: Roadmap
▪ 7 Issues fonctionnelles planifiées pour faire évoluer le système (Juin 2016)
▪ Un travail pour permettre la validation des requêtes en production
▪ Analyse de performances
▪ Optimisation des traitements
▪ Evolutions des validateurs/JSON Schema
▪ Amélioration du processus de mise en cache
▪ Une intégration sous forme de bundle Symfony (Sept 2016) suivant 2 modes:
▪ Listener de requêtes
▪ Annotation
▪ Objectif: Profiter des fonctionnalités du Framework pour matcher les Routes avec les paths swagger
directement dans les Controllers, Intégration au système de gestion du cache de Symfony.
▪ Intégration avec Nelmio/ApiDocBunde (Compatible avec le format OpenAPI)

13. Merci
Si vous avez des questions…