ISD SOA Designer
Copyright © 2008, 2023 Obeo – All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v2.0
SOA Designer permet de modéliser des composants métiers, avec leurs services et les structure de données qu’ils manipulent (Data Transfer Objects).
SOA Designer apporte le point de vue SOA Views qui permet de :
- Modéliser les composants et les liens entre eux,
- Modéliser les contrats des composants (interfaces et services),
- Modéliser les DTOs, leur structure et les relations entre eux,
- Organiser les DTOs en packages,
- Modéliser l’exposition REST des services et gérer le format Open API (Swagger).
Un assistant permet la création de modèles SOA. Cet assistant est accessible via le menu :
File > New > Other … > SOA Model (Catégorie IS Designer) :
Cet assistant permet de définir
- le nom du modèle à créer (l’extension du modèle est automatiquement ajoutée à la fin du nom en grisée et en italique s’il n’y a pas d’extension précisée),
- le projet ou répertoire de destination pour cette nouvelle ressource :
Une fois l’assistant validé, un modèle vide est créé, et les représentations SOA Diagram, DTO Namespaces Hierarchy et DTO Physical Names sont créées.
Les représentations SOA Diagram et DTO Namespaces Hierarchy sont ouvertes afin de commencer l’édition :
Lorsqu’un modèle soa est créé à l’aide de ce wizard, les points de vues SOA Views, SOA (Safr@n Consolidated view) et Environment View sont activés.
- Le point de vue SOA Views est décrit dans la section suivante,
- Le point de vue SOA (Safr@n Consolidated view) est décrit dans la section de documentation Obeo Network – SOA,
- Le point de vue Environment Views fournit les vues de propriétés EEF communes avec d’autres designers tel que pour le Namespace par exemple.
Le point de vue SOA Views fourni par SOA Designer est dédié à la modélisation des composants métier. Il permet de visualiser et modifier un modèle SOA au travers de différents types de diagrammes et vues de propriétés.
L’ouverture d’une session de travail sur un modèle SOA se fait par l’une des manières classiques à un Modeling Project :
- En ouvrant le Modeling Project contenant le modèle,
- En double-cliquant sur un fichier *.aird existant,
- En faisant un glisser/déposer d’un fichier *.soa dans un Modeling Project sur la vue Model Explorer,
- En convertissant un projet contenant le modèle SOA en un Modeling Project.
L’ouverture de l’assistant Viewpoints Selection permet de vérifier que le point de vue SOA Views est bien activé.
Cet assistant est accessible dans le menu contextuel du Modeling Project sous l’entrée de menu :
Viewpoint Selection
Une fois le point de vue SOA Views activé il est possible de créer ou visualiser les diagrammes SOA Views.
Chaque type de diagramme est rattaché à un concept SOA précis. Par exemple, un DTO Diagram est rattaché à un Namespace.
Pour créer un diagramme d’un certain type, sélectionner l’élément du modèle auquel rattacher le diagramme dans la vue Model Explorer puis, avec un clic droit, sélectionner le menu :
New… > #Nom du diagramme#
Renseigner le nom du diagramme et valider.
Par exemple sur l’élément racine Components, deux types de représentation peuvent être créés comme le montre la capture d’écran suivante :
Une fois créé, le diagramme apparaît dans l’arbre de la vue Model Explorer sous l’élément sur lequel il a été créé, et l’éditeur de diagramme est ouvert prêt à modéliser.
Si il est fermé, un diagramme peut être ouvert en double-cliquant sur le noeud correspondant dans la vue Model Explorer.
Attention, bien qu’ils continuent d’exister et qu’ils soient bien sauvegardés, les diagrammes des points de vues non activés sont filtrés de la vue Model Explorer. Celle-ci ne présente que les diagrammes des points de vue activés sur le Modeling Project.
Les diagrammes suivants peuvent être ouverts en mode “Vue Partielle”. Le fonctionnement des Vues Partielles est décrit dans la section ISD – Outillage environnement / Vues Partielles
- SOA Diagram
- Component Contract Diagram
Le SOA Diagram offre une vue de haut niveau sur un modèle SOA, il peut être créé sur l’objet racine Components.
Il permet de modéliser les composants métiers, les services qu’ils fournissent, les services qu’ils requièrent ainsi que des liens entre les composants. Ces liens créés entre services requis et services fournis expriment qu’un service fourni par un composant réponds à un besoin de service requis par un autre composant.
Le diagramme permet d’afficher et manipuler les éléments suivants :
- Component : composant métier,
- Provided Service : service métier fourni par un composant,
- Required Service : service métier dont un composant a besoin pour fonctionner,
- Les liens entre services fournis et services requis.
Les outils fournis par la palette sont :
 |
Création d’un composant métier. |
 |
Création d’un service métier fourni par un composant. |
 |
Création d’un service métier requis par un composant. |
 |
Création d’un lien depuis un service requis vers un service fourni. Permet d’indiquer quel composant fournit les services nécessaires au fonctionnement d’un autre composant. |
 |
Ajout d’un composant externe sur le diagramme. Permet de faire apparaitre un composant défini dans un autre modèle SOA pour créer des relations avec les composants affichés. Cet outil est disponible par l’activation du calque External Components |
Il est possible de naviguer depuis ce diagramme vers un diagramme Component Contract (décrit ci-après) par l’une des actions suivantes :
- Action New > Component Contract du menu contextuel sur un Component : crée et ouvre un nouveau diagramme Component Contract,
- Action Open > #Nom d’un diagramme# du menu contextuel sur un Component : ouvre un diagramme Component Contract existant,
- Double-clic sur un Component : ouvre le premier diagramme Component Contract trouvé si il existe, propose la création d’un diagramme Component Contract sinon.
Le Component Contract Diagram permet de modéliser le détail d’un Component, il peut être créé sur un Component.
Il permet de modéliser :
- les services métiers fournis et requis par le composant,
- les opérations définies par les services,
- les paramètres d’entrée, de sortie et d’erreur des services.
Le diagramme permet d’afficher et manipuler les éléments suivants :
- Provided Service : service métier fourni par le composant,
- Required Service : service métier dont le composant a besoin pour fonctionner,
- Operation : opération d’un service,
- Input Parameter : paramètre d’entrée d’une opération
- Output Parameter : paramètre de sortie d’une opération
- Fault Parameter : cas d’erreur pour une opération
Les outils fournis par la palette sont :
 |
Création d’un service métier fourni par un composant. |
 |
Création d’un service métier requis par un composant. |
 |
Création d’une opération d’un service. |
 |
Création d’un paramètre d’entrée d’une opération. |
 |
Création d’un paramètre de sortie d’une opération. |
 |
Création d’un cas d’erreur d’une opération. |
Les calques sont activables dans la barre d’outils du diagramme par le menu déroulant 
.
Le Component Contract Diagram fournit le calque Meta Types qui ajoute l’information du méta-type (le type du type) de l’attribut dans le libellé des paramètres (pour les cas autres que les types primitifs).
Ceci permet de dissiper la confusion qui peut arriver entre un DTO et un Entity portant le même nom.
Ici, DTO est ajouté dans la constitution du libellé du paramètre “books” :
Les DTO sont organisés en Namespaces (autrement appelés packages).
Le diagramme DTO Namespaces Hierarchy est destiné à gérer l’ensemble de cette hierarchie de Namespaces et peut être créé sur l’objet racine Components.
Il permet de créer, modifier ou supprimer des packages ainsi que d’accéder facilement (par double clic ou menu contextuel sur les Namespaces) aux diagrammes de DTOs d’un package.
Le diagramme permet d’afficher et manipuler les éléments suivants :
- Namespace : chaque Namespace contenu dans l’élément racine est affiché. Les Namespaces contenus par d’autres sont représentés à l’intérieur de leur Namespace parent. L’icône d’un Namespace est en noir et blanc si le Namespace est vide, en couleur sinon.
- Dépendance : l’affichage des dépendances peut être activé ou désactivé via le layer Dependencies. Les dépendances entre Namespaces sont représentées par des liens pouvant être fléchés à une ou deux extrémités. Les dépendances sont calculées à partir du contenu de chacun des Namespace. Une dépendance est identifiée entre deux Namespaces si il existe un lien d’héritage, une référence ou l’utilisation d’une Enumeration pour typer un attribut entre un DTO d’un Namespace et un autre. Si il est non nul, le nombre de dépendances identifiées est indiqué sur l’extrémité du lien correspondant, et cette extrémité est décoré d’une flèche. Les dépendances entre les packages d’une même lignée de contenance ne sont pas affichées. L’affichage des dépendances peut être activé ou désactivé via le layer Dependencies. Les namespaces dits “externes” sont également affichés dans ce layer. Un namespace externe est un namespace contenant une entité externe liée à une entité présente dans un namespace affiché par le diagramme (voir External DTO dans la section Diagramme de DTOs ci-après).
Les outils fournis par la palette sont :
 |
Création d’un Namespace. Un Namespace peut être créé sur le fond du diagramme ou à l’intérieur d’un autre Namespace. |
 |
Création d’un Namespace par duplication d’un Namespace d’Entité. Voir le diagramme “Diagramme de DTOs” ci-dessous. |
Il est possible de naviguer depuis ce diagramme vers des diagrammes DTO Diagram par l’une des actions suivantes :
- Action New > DTO Diagram du menu contextuel sur un Namespace : crée et ouvre un nouveau DTO Diagram,
- Action Open > #Nom d’un diagramme# du menu contextuel sur un Namespace : ouvre un DTO Diagram existant,
- Double-clic sur un Namespace : ouvre le premier DTO Diagram trouvé si il existe, propose la création d’un DTO Diagram sinon.
Un diagramme de DTOs (DTO Diagram) permet de gérer les DTOs d’un Namespace, il peut être créé sur un Namespace.
Le diagramme permet d’afficher et manipuler les éléments suivants :
- DTO : Data Transfer Object, type de donnée destiné à être utilisé par les services, il es représenté par un conteneur rectangulaire.
- Attribute : attribut d’un DTO, un attribut porte notamment un type et une multiplicité. Le type qu’il porte peut être un type primitif ou une enumération (et non pas un autre DTO). Il est représenté comme élément de liste à l’intérieur de la représentation d’un DTO.
- Relation : relation entre deux DTOs. Permet de structurer le modèle de données représenté par les DTO. Les types de relations supportées sont relation unidirectionelle, bidirectionelle, de composition. Une relation est représentée par un lien pouvant être décoré d’une flèche ouverte dans le cas d’une relation directionelle, et d’un losange dans le cas d’une relation de composition.
- Inheritance : relation de spécialisation d’un DTO par un autre. Une relation de spécialisation est représentée par un lien décoré d’une flèche fermée pointant vers le DTO spécialisé. Une seule relation de spécialisation peut être définie par DTO.
- Enumeration : Type de donnée pouvant servir au typage d’un attribut ou d’un paramètre de service. Une Enumeration prends sa valeur dans un ensemble fini de literaux qui lui sont propres. Une Enumeration est représentée par un conteneur rectangulaire.
- Literal : Literal d’une Enumeration_. Il fait partie de la définition de l’_Enumeration et représente l’une des valeurs que peut prendre l’_Enumeration_. Un Literal est représenté comme élément de liste à l’intérieur de la représentation d’une Enumeration.
- Namespace : Namespaces contenus directement dans le Namespace contextuel au DTO Diagram.
Les outils fournis par la palette sont :
 |
Création d’un sous Namespace. |
 |
Création d’un Namespace à partir d’un Namespace entités. |
 |
Création d’un DTO. |
 |
Création de DTOs à partir d’entités (cf. description ci-dessous). |
 |
Création d’un attribut de DTO. |
 |
Création d’une énumération. |
 |
Création d’une valeur d’énumération. |
 |
Création d’une relation simple. |
 |
Création d’une relation de composition. |
 |
Création d’un lien d’héritage. |
 |
Création d’une relation simple bidirectionnelle. |
 |
Création d’une relation de contenance bidirectionnelle. |
 |
Ajout d’un DTO externe au Namespace courant. Permet de faire figurer sur le DTO Diagram un DTO défini dans un autre Namespace_, donnant la possibilité de créer des relations inter-_Namsepace. Cet outil est activable via le calque External DTOs |
L’outil de création de DTOs à partir d’entités permet de reproduire un modèle de DTO à partir d’un modèle d’entités. Une boîte de dialogue permet de choisir les entités et les relations à prendre en compte. Les entités choisies peuvent être de différents packages mais la structure de ces packages n’est pas reproduite. Les DTO créés sont tous dans le package courant du diagramme.
Des DTOs et des relations sont créées pour chaque entité et chaque référence sélectionnés. Les attributs ne sont pas dupliqués, il sont partagés avec les entités grâce à la référence Associated Types accessible dans la vue des propriétés du DTO. La modélisation des entités est décrite dans la documentation de ISD – Entity Designer .
L’outil de création de package à partir d’un package d’entités permet de reproduire un modèle de DTO à partir d’un modèle d’entités en reproduisant la structure des packages. L’outil présente la hiérarchie des packages d’entités accessibles depuis le diagramme courant.
La sélection d’un élément dans l’arbre entraîne la sélection de ses sous éléments, permettant de procéder à une sélection par soustraction plutôt que par addition.
La désélection d’un élément dont tous les sous éléments sont sélectionnés entraîne la désélection de toute la hiérarchie. De manière synthétique :
- Un clic sur un élément décoché coche l’élément et tous ses sous éléments.
- Un clic sur un élément coché décoche l’élément et tous ses sous éléments.
- Un clic sur un élément partiellement coché décoche l’élément et ne change pas l’état des sous éléments.
Un élément est marqué partiellement sélectionné si certains de ses sous éléments sont sélectionnés mais pas tous.
Lorsque tous les sous éléments d’un élément sont sélectionnés, celui-ci devient sélectionné.
Les éléments marqués comme partiellement sélectionnés sont pris en compte par le traitement de duplication.
La sélection d’une relation induit la sélection de l’entité ciblée par celle-ci. Il est possible de désélectionner cette entité, mais toute relation dont les deux types source et cible ne sont pas sélectionnés ne sera pas dupliquée.
Le bouton finish est activé si au moins un package est sélectionné ou partiellement sélectionné.
Le traitement crée les packages de plus haut niveau sélectionnés dans le package du diagramme courant.
Les éléments pris en compte pour la duplication sont ceux dont :
- la case à cocher est cochée ou partiellement cochée,
- la lignée des parents est complètement sélectionnée jusqu’au package de plus haut niveau sélectionné.
En plus des outils définis par la palette, l’outil de drag and drop permet de déplacer un DTO d’un namespace à un autre.
Le drag and drop depuis le Model Explorer d’un DTO d’un autre Namespace que le Namespace sur lequel est défini le DTO Diagram a pour effet de déplacer le DTO depuis son Namespace d’origine dans le namespace du diagramme.
Le DTO ainsi déplacé reste référencé là où il l’était, comme par exemple en type de paramètre d’une opération SOA ou en référence sur une Relation. Si le calque External DTOs est activé, alors les DTO externes figurent sur le diagramme avec une couleur différente et un label représentant leur nom qualifié :
Les attributs de DTO et les paramètres de services sont pourvus de champs minimum, maximum et optionellement pattern.
La nature de ces champs dépend de la nature du type, qui peut être textuel (essentiellement String_), numérique (_Integer, Long, Float_, etc.) ou autre (_Boolean, Binary, etc.).
Pour un type de nature textuel :
- minimum : longueur minimale du texte
- maximum : longueur maximale du texte
- pattern : expression régulière (format ECMA 262) à laquelle le texte doit se conformer
Pour un type de nature numérique :
- minimum : valeur minimale requise
- maximum : valeur maximale autorisée
- pattern : non-applicable
Pour un type de nature autre ces champs sont non-applicables.
Ces champs sont exploités par la génération et l’import OpenAPI (Swagger).
L’exposition d’un composant consiste à publier tout ou partie des services qu’il fournit de manière à les rendre accessibles à des clients (autres composants ou systèmes, et potentiellement au travers d’un réseau).
L’ensemble des services exposés d’un composant constitue son API (Application Programming Interface).
Dans SOA Designer, le type d’exposition est paramétrable au niveau d’une Operation, sur l’onglet principal de la vue de propriétés :
La notion de visibilité (Public/Privé) fait référence à la notion du même nom définie par les langages orientés objet et concernant les méthodes de classes. Ainsi, une Operation publique sera accessible depuis les implémentations des autres Operations du Composant ou bien depuis un autre composant destiné à être déployé dans la même application, mais il ne sera pas accessible depuis un autre système.
La notion de pagination (Paged_) indique lorsque les résultats retournés par l’opération sont paginés. Lorsque l’operation est paginée, il est possible d’indiquer quels paramètres définissent l’index de la page (Page_), et le nombre de résultats par page (Size).
La notion d’exposition fait référence à la publication par une technologie permettant de la rendre accessible depuis un autre système, et çe typiquement au travers d’un réseau. C’est ce qu’adresse par exemple de manière non exaustive les technologies REST, SOAP ou gRPC. Ainsi, pour être exposée, une opération doit avoir une visibilité Publique.
SOA Designer propose les types d’exposition suivants :
- NONE : Non exposée,
- REST : Exposée en web service par Representational State Transfer
- SOAP : Exposée en web service par Simple Object Access Protocol
Le type d’exposition couvert par SOA Designer est REST. Le type d’exposition SOAP n’est disponible dans le studio qu’à titre indicatif, aucun outillage spécifique n’ayant été développé pour l’exploiter.
L’icone des Operations diffère suivant le type d’exposition :
 |
Privée | (type d’exposition ignoré) |
 |
NONE | (opération publique non exposée) |
 |
REST | (opération publique exposée en REST) |
 |
SOAP | (opération publique exposée en SOAP) |
SOA Designer permet de :
- modéliser des API Rest via un modeleur graphique basé sur Sirius,
- exporter / importer ces API au format Swagger (conforme à la norme OpenAPI),
- prévisualiser un export Swagger dans une vue web Swagger-UI.
La terminologie utilisée par SOA Designer provient du champ lexical de SOA (Service Oriented Architecture), dans lequel le concept de service est défini comme une fonction ou fonctionnalité. Cette définition est suffisament large pour autoriser un raffinement de la notion de Service en Operations, tel qu’il est fait dans SOA Designer.
Or, cette notion d’_Operation SOA_ est celle qui se prête à être en correspondance avec la notion de Service REST.
Le concept de Service SOA quand à lui, est mis en correspondance avec le concept de Tag défini par la norme OpenAPI.
Enfin, le concept de Component SOA est mis en correspondance avec le concept d’API, ce qui est appelé de manière générique Composant d’Exposition.
De manière synthétique, voici les correspondances clé entre les deux terminologies :
| SOA Designer | OpenAPI |
| Component | OpenAPI |
| Service | Tag |
| Operation | Service |
La suite de ce document privilègie la terminologie SOA. Les exceptions à cette règle seront clairement explicitées.
Le concept de SOA Designer correspondant à une API REST OpenAPI est le Component.
Les données d’exposition sont accessibles via l’onglet Exposition de la vue des propriétés :
Une URI peut être définie à chaque niveau de profondeur dans le modèle sur les concepts Component, Service et Operation :
L’URL d’une Operation peut donc être calculée par la concaténation de l’URL du Component et de chacune des URI sur les trois niveaux Component, Service et Operation.
Des serveurs peuvent être définis au niveau du Component. Pour chaque serveur, l’URL correspondante doit être indiquée, et une description peut éventuellement être précisée.
Enfin, des informations générales sur l’API peuvent être définies dans la vue des propriétés:
Les champs Terms of Service et URL attendent une entrée au format URL:
Le champs Email requiert une adresse e-mail valide: lettres, chiffres et/ou charactères spéciaux, suivis d’un ‘@’, et terminant par un serveur eventuellement séparé avec des points.
E.g., nom.prenom@intradef.gouv.fr ou contact@obeo.fr
Les champs attendant une URL sont eux aussi vérifiés, et attendent une URL valide: commençant par http://, https://, ftp://, ou file://, et suivi de charactères (lettres, chiffres, symboles) terminant par une extension précédée d’un point ‘.’.
Le concept en correspondance avec le Tag OpenAPI est le concept Service.
L’onglet principal du service permet d’en définir le nom, l’onglet Exposition permet d’en définir l’URI. Celle-ci peut rester vide.
Le concept en correspondance avec le Service OpenAPI est le concept Operation. Lorsqu’un type d’exposition autre que NONE est sélectionné comme expliqué au paragraphe Types d’exposition , l’onglet Exposition devient visible et accessible :
Le verbe correspond au verbe HTTP et peut prendre l’une des valeurs : GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, TRACE.
Comme au niveau Component, il est possible de définir l’URI d’une Operation ainsi qu’une liste de serveurs.
Dans le cas où l’opération définit des paramètres d’entrée, ceux-ci sont listés dans la section Input Parameters_, qui offre la possibilité de définir le mode de passage et les identifiants REST de chacun d’eux. Ceci est expliqué plus en détail ci-dessous dans la section Modélisation d’un paramètre d’entréeparameter .
Le contenu de l’onglet Exposition d’un paramètre n’est pas le même pour un paramètre d’entrée, de retour ou d’erreur.
L’identifiant REST est un moyen pour identifier un paramètre autrement que par son nom, et a des particularités liées au mode de passage du paramètre.
Pour un mode de passage BODY, l’identifiant REST n’a pas de sens.
Lorsque le mode de passage BODY est sélectionné dans la liste déroulante, la vue de propriétés affiche à côté de celle-ci une zone de texte non modifiable affichant le texte “body” :
Pour un mode de passage PATH_, l’identifiant REST doit correspondre à l’un des identifiants définis entre accolades dans l’URI de l’_Operation.
Lorsque le mode de passage PATH est sélectionné dans la liste déroulante, la vue de propriétés affiche à côté de celle-ci une autre liste déroulante proposant un choix déduit de l’analyse de l’URI de l’_Operation_. Ainsi, si l’URI est “/{country}/{author}”, la liste déroulante proposera les deux choix “country” et “author” :
Suite à une édition de l’URI d’une Operation, il est possible que la valeur de l’identifiant REST d’un Parametre PATH ne soit pas dans l’URI. Dans ce cas un message d’erreur est affiché :
Pour un mode de passage QUERY, COOKIE ou HEADER, l’identifiant REST permet d’identifier le paramètre soit dans l’URL d’appel du service REST, soit dans le cookie, soit dans le header HTTP.
Lorsque l’un de ces modes de passage est sélectionné dans la liste déroulante, la vue de propriétés affiche à côté de celle-ci une zone de texte libre permettant la saisie de l’identifiant :
OpenAPI permet de plus de spécifier des contraintes sur les valeurs autorisées pour un paramètre d’entrée (ou plus généralement pour toute donnée typée).
Ces contraintes sont représentées dans SOA Designer via les champs minimum, maximum et/ou pattern.
L’interprétation de ces champs dépend de la nature du type du paramètre d’entrée : texte (essentiellement String_) ou valeur numérique (_Long, Float, etc.).
Pour un paramètre dont le type est de nature texte :
- minimum : longueur minimale du texte
- maximum : longueur maximale du texte
- pattern : expression régulière (format ECMA 262) à laquelle le texte doit se conformer
Pour un paramètre dont le type est de nature valeur numérique :
- minimum : valeur minimale requise
- maximum : valeur maximale autorisée
- pattern : non-applicable
Lorsqu’une opération est définie comme étant paginée, des listes déroulantes apparaissent dans la vue des propriété de l’opération afin de spécifier les paramètres entrant pouvant être utilisés pour définir l’index de la page, ainsi que le nombre d’éléments par page.
Dès lors qu’une opération est paginée, sa représentation dans le diagramme est décorée d’une icone supplémentaire:
Enfin, dans le cas où l’operation est paginée, une extension de propriété peut-être définie afin d’indiquer lors de l’export OpenAPI si l’opération est paginée.
L’onglet Exposition des vues de propriétés pour un paramètre de retour ou d’erreur présente la même IHM permettant de saisir un code de status et une description :
Le bouton à droite de la zone de texte Status Code ouvre une boîte de dialogue permettant de saisir facilement parmi une liste de valeurs par défaut des couples code / description.
Le dialogue propose les codes de succès dans le cas d’un paramètre de sortie, et des codes d’erreur dans le cas d’un paramètre d’erreur :
Des types de média peuvent être définis sur un paramètre exposé en REST quel que soit sa direction (paramètre entrant, sortant ou d’erreur). L’onglet “Exposition” de la vue des propriétés présente la liste des types de média pour un paramètre donné :
Un double clic sur un type de média ouvre un dialogue d’édition :
Le champ “Example” est un champ texte, destiné à recevoir une sérialisation textuelle d’un exemple.
Le champ “Identifier” est un champ libre, le bouton “…” est une aide à la saisie qui permet de choisir parmi les types de média les plus courants :
Les schemas de sécurité sont définis sur l’onglet Security Schemes de la vue de propriétés d’un Component :
Cette vue permet de créer (
), supprimer (
) et réordonner (
, 
) les Security Schemes du Component.
La création d’un Security Scheme déclenche l’affichage d’une boîte de dialogue permettant de spécifier son type, son nom et sa description :
Un double clic sur un Security Scheme déclenche l’affichge d’un dialogue d’édition permettant de spécifier les données spécifiques au type de Security Scheme.
- Api Key:
Un Security Scheme de type Api key permet la définition d’une clé, ainsi que la spécification de sa localisation: dans le header, la requête, ou le cookie.
- HTTP:
Un Security Scheme de type HTTP défini un schéma d’authentification de type Basic, ou Bearer.
Dans le cas d’un schéma d’authentification de type Basic, le server attendra un mot de passe de type username:password, encodé en base-64.
Dans le cas d’un schéma d’authentification de type Bearer, le bearer-format définit la manière dont le token est stocké.
- OAuth2:
- Open ID:
Les Security Scheme de type OAuth2 et Open ID requièrent la spécification de Flows, ainsi que leurs Scopes respectifs:
Les Flows représentent des scénarios que le client effectue afin d’obtenir l’accès à un token d’authentification.
Chaque flow propose des Scopes. Ces scopes définissent un droit d’accès (restreint) a une fonctionnalité prodiguée par le serveur.
L’édition des valeurs saisies est modifiable par la suite en double-cliquant sur un SecurityScheme dans cette même vue de propriétés, ou bien dans la vue de propriétés d’un SecurityScheme lorsque celui-ci est séléctionné dans la vue Model Explorer :
Lorsqu’ils existent, les SecuritySchemes sont présentés dans la vue Model Explorer au niveau de profondeur suivant celui du Component.
L’utilisation des schémas de sécurité est configurable via l’onglet Security de la vue des propriétés d’une Operation (quelque soit son mode d’exposition ou sa visibilité) ou d’un Service.
Nous prenons une Operation comme example d’utilisation des schémas de sécurité dans le reste de cette section mais ceux-ci s’utilisent de la même manière sur un Service:
Cette vue permet de sélectionner les SecuritySchemes à appliquer à l’_Operation_ (
), supprimer une affectation de Security Scheme à l’_Operation_ () et réordonner (, ) les applications de Security Schemes.
La suppression ne supprime pas le Security Scheme du modèle, mais simplement son affectation à l’_Operation_.
La sélection des Security Schemes ouvre une boîte de dialogue permettant d’ajouter, retirer, réordonner les affectations de Security Schemes à l’_Operation_ :
Un double-clic sur un Security Scheme de type OAUTH2 ou OPEN_ID_CONNECT dans l’onglet Security ouvre une boîte de dialogue permettant de sélectionner les scopes à appliquer :
Les Security Schemes accessibles pour une affectation à une Operation sont ceux définis au niveau du Component auquel appartient l’_Operation_.
Quand au moins un Security Scheme est appliqué à une Operation_, celle-ci est décorée avec l’icone !pics/exposition/IconSecurityScheme.gif!. :
Si son Service parent applique un Security Scheme_, l’_Operation est décorée avec l’icone 
.
Quand au moins un Security Scheme est appliqué à une Operation (soit directement, soit indirectement via son Service parent), son icone dans la vue Model Explorer est elle aussi décorée avec l’icone 
:
Bien que la spécification OpenAPI tente de tenir compte de la plupart des cas d’utilisation, des données supplémentaires peuvent être ajoutées pour étendre la spécification.
Les propriétés des extensions sont implémentées sous forme de champs à motifs qui sont toujours préfixés par « x- », par exemple, x-internal-id.
Les éléments sur lequels il est possible d’ajouter des extensions de propriétés disposent d’une section supplémentaire “Properties Extensions” dans l’onglet “Exposition” de la vue Properties.
Cette section liste les extensions de propriétés, et permet d’en ajouter, modifier et supprimer.
Ce dialogue est utilisé pour créer ou modifier une extension de propriété :
- le champ de saisie “Key” permet de saisir l’identifiant de l’extension de propriété. Le préfixe “x-” peut être omis il est alors automatiquement ajouté.
- le champ de saisie multilignes “Value” permet de renseigner la valeur de l’extension de propriétés sous forme d’une chaîne de caractères.
- la liste déroulante “Context” permet de choisir l’élément OpenApi/Swagger sur lequel sera attaché l’extension de propriétés lors de la génération.
Les contextes possibles pour chaque type d’élément SOA sont présentés dans le tableau ci-dessous.
| Elément SOA | Contextes possibles |
|---|---|
| Composant | OpenAPI, Server, Paths |
| Contact | Contact |
| Information | Info |
| Licencee | License |
| Service | Tag |
| Type | Schema |
| Attribut | Schema |
| Référence | Schema |
| Opération | Operation, PathItem, ApiResponses |
| Paramètre | Parameter, RequestBody, ApiResponse, Schema |
| Type de média | MediaType |
| Exemple | Example |
Les extensions de propriétés sont générées lors d’un export Swagger et insérées dans le modèle lors d’un import Swagger.
Une fois que les informations requises à la définition d’une API Rest sont modélisées, il est possible de générer un fichier de spécification Swagger.
Une fonctionnalité de prévisualisation est disponible en menu contextuel du Component :
Celle-ci ouvre un navigateur montrant le résultat de l’export dans Swagger UI, permettant de s’assurer que la génération produit un résultat satisfaisant :
La fonctionnalité d’export permet de produire des fichier Swagger au format yaml ou json. Elle est disponible en menu contextuel sur l’objet racine Components ou bien sur l’objet Component. Dans les deux cas, une boîte de dialogue invite à choisir le dossier de destination :
Suite à la validation du Dialogue, un fichier est généré par Component, avec la convention de nommage suivante :
<Nom du Component>-<Version du Component>.<yaml|json>
La fonctionnalité d’import Swagger permet d’importer un fichier de spécifiction Swagger dans SOA Designer sous forme d’un Component. L’import incrémental n’est pas supporté. Si un Component du nom de l’API existe déjà dans le modèle SOA, alors l’import échoue avec un message d’erreur du type “Component with name BookStore already exist.”.
La fonctionnalité d’import Swagger est disponible en menu contextuel sur l’objet racine Components :
En cas de succès suite à l’import, un nouveau Component est créé, prêt à être utilisé dans un ensemble plus vaste de Components SOA.
La gestion des exigences pour un modèle SOA utilise le mécanisme transverse de gestion des exigences. Pour plus de détails, voir Obeo Network – Requirements Tooling .
Il est possible d’attacher de la documentation aux éléments d’un modèle SOA. Le mécanisme utilisé est le mécanisme transverse de gestion de la documentation : Obeo Network – Documentation Tooling .
Il est possible de créer des diagrammes d’interaction pour les éléments d’un modèle SOA. Voir la documentation Obeo Network – Interaction Tooling .
Il est possible de créer des diagrammes de machines à états pour les éléments d’un modèle SOA. Voir la documentation Obeo Network – State Machine Tooling .