Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update swagger.yaml #6

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update swagger.yaml #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 18 additions & 173 deletions swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
openapi: 3.0.0
info:
version: '1.1.0'
version: '1.2.0'
title: Get CRI Photos

servers:
Expand All @@ -12,183 +12,29 @@ servers:
default: https

paths:
'/access/{id}/photos':
'/photos/':
get:
tags:
- Get Photo's Metadata
summary: Get Photos metadatas for a given access id (RefPrestationPrise)
operationId: getPhotosByAccess
- Get Photos Metadata
summary: Get Photos metadatas for a given access id (RefPrestationPrise) or id (ReferenceCommandeSousTraitantOI) or id (ReferenceCommandePriseInterneOc)
operationId: getPhotosMetadata
parameters:
- name: id
in: path
- name: accessId
in: query
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, je n'avais pas fait attention à ça (comme quoi le difff, ça sert :-)).

Pourquoi être passé en query plutôt que path ? La ressource est moins claire à la consultation non ?
Cf :
image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Je reviens à la charge sur le sujet car en plus de passer de path à query, vous supprimez les différentes ressources et créer un seul point d'entrée permettant les différentes consultations sur les différents identifiants en même temps.

Personnellement, je suis foncièrement contre. Nous retombons dans les galères des autres WS où le consommateur du service / API peut envoyer plusieurs identifiants dans différents champs, qui potentiellement ne sont pas cohérents les uns avec les autres (une prestation qui n'a rien à voir avec la commande par exemple)... et le fournisseur de service doit gérer tout cela :-(

Notre volonté au départ était bien de fiabiliser ces échanges, et de ne pas rentrer dans de la normalisation inutile via document word (comme les différentes ressources permettent d'être discriminant)... donc N identifiants, N endpoints, ou alors une seule ressource, requêtable via un objet gérant le polymorphisme, avec N implémentations de cet objet ne portant chacune qu'un seul identifiant (mais du coup ça se complique)... Sinon tout le monde ira de sa sauce encore une fois.

Si je ne suis pas clair, on peut s'appeler @mrongier .
Un avis @NicolasD-Altitude @AltitudeAntoineS ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bonjour @aminvielledebat ,

Merci pour ton retour. Pour moi c'est très clair, et c'est effectivement le défaut de la solution. De notre coté, on n'avait pas identifier comme un problème complexe le fait de gérer les multi input (on en accepte qu'un à la fois).

Avec la version 1.1.0, d'un point de vu OC, nous allons devoir mettre en oeuvre différentes ressources, qui, pour des besoins internes OC, existent déjà et ne sont pas toujours portées par les mêmes systèmes techniques. Cela va nous imposer de développer une couche d’unification en front avec les OI. C’était l'origine de notre proposition.

Manuel

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello Manuel,

Ce n'est clairement pas un sujet complexe à implémenter, mais qui peut vite le devenir fonctionnellement si l'info n'est pas clairement explicitée dans un doc adhoc. (Sinon rien n’empêcherait un OC d'imposer la fourniture de la ref interne et de la ref prestation, ou encore d'un autre identifiant par ex).

Personnellement, je suis plutôt adepte des outils qui imposent des choix d'implémentation sans avoir à se poser la question d'un potentiel doc ad'hoc. Pas de question, pas de souci :-)

Un avis côté Altitude @NicolasD-Altitude ?

description: Infrastructure Operator Internal Reference (RefPrestationPrise)
required: true
schema:
type: string
- name: Authorization
in: header
description: >-
Credentials to authenticate an operator, it is a token
with scheme Negotiate.
required: false
schema:
type: string
- name: X-Request-Id
in: header
description: >-
Unique identifier of the request (uuid type recommended).
required: true
schema:
type: string
minLength: 0
maxLength: 36
- name: X-Client-Id
in: header
description: Building Operator Id
required: true
schema:
type: string
responses:
'200':
description: Get Metadata Ok
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Photo'
links:
GetPhotoById:
$ref: '#/components/links/GetPhotoById'
'202':
description: Photo not yet available
'204':
description: Photo will never be available
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Not Authorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'

'/order/{internalReference}/photos':
get:
tags:
- Get Photo's Metadata
summary: Get Photos metadatas for a given order
operationId: getPhotosByOrder
parameters:
- name: internalReference
in: path
description: Commercial Operator Internal Reference (ReferenceCommandePriseInterneOc)
required: true
schema:
type: string
- name: Authorization
in: header
description: >-
Credentials to authenticate an operator, it is a token
with scheme Negotiate.
- name: orderId
in: query
description: Infrastructure Operator Internal Reference (ReferenceCommandePriseInterneOc)
required: false
schema:
type: string
- name: X-Request-Id
in: header
description: >-
Unique identifier of the request (uuid type recommended).
required: true
schema:
type: string
minLength: 0
maxLength: 36
- name: X-Client-Id
in: header
description: Building Operator Id
required: true
schema:
type: string
responses:
'200':
description: Get Metadata Ok
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Photo'
links:
GetPhotoById:
$ref: '#/components/links/GetPhotoById'
'202':
description: Photo not yet available
'204':
description: Photo will never be available
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Not Authorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'

'/intervention/{id}/photos':
get:
tags:
- Get Photo's Metadata
summary: Get Photos metadatas for a given itervention
operationId: getPhotosByIntervention
parameters:
- name: id
in: path
description: Intervention id (ReferenceCommandeSousTraitantOI)
required: true
- name: interventionId
in: query
description: Infrastructure Operator Internal Reference (ReferenceCommandeSousTraitantOI)
required: false
schema:
type: string
- name: Authorization
Expand Down Expand Up @@ -260,13 +106,13 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'


'/photo/{id}':

'/photos/{id}':
get:
tags:
- Get Photo
summary: Get Photo
summary: Get Photo in jpeg or png format
operationId: getPhoto
parameters:
- name: id
Expand Down Expand Up @@ -364,7 +210,6 @@ components:
- id
- type
- mimeType
- url
properties:
id:
type: string
Expand Down Expand Up @@ -431,4 +276,4 @@ components:
operationId: getPhoto
parameters:
id: '$response.body#/photos/0/id'
description: The `id` value returned in the response can be used as the `id` parameter in `GET /photo/{id}`.
description: The `id` value returned in the response can be used as the `id` parameter in `GET /photos/{id}`.