web-dev-qa-db-fra.com

Quelle est la bonne façon de déclarer une date dans un fichier OpenAPI / Swagger?

Quelle est la bonne façon de déclarer une date dans un objet swagger-file? Je pense que c'est:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date

Mais je vois beaucoup de déclarations comme celles-ci:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date
    pattern: "YYYY-MM-DD"
    minLength: 0
    maxLength: 10

Merci.

swaggeropenapi
16
Patrick Savalle

Le Spécification OpenAPI indique que vous devez utiliser:

type: string
format: date  # or date-time

Le modèle à utiliser est défini dans RFC 3339, section 5.6 .
Donc pour date la valeur devrait ressembler à "2018-03-20" et pour date-time "2018-03-20T09: 12: 28Z".

Je ne sais pas pourquoi les gens spécifient explicitement le pattern parce qu'il est implicitement défini dans la définition de format.

24
Pascal

pattern devrait être une expression régulière. Ceci est indiqué dans le Spécification OpenAPI .

pattern (Cette chaîne DEVRAIT être une expression régulière valide, conformément au dialecte des expressions régulières ECMA 262)

En effet, les objets OpenAPI sont basés sur la spécification de schéma JSON.

OpenAPI 2.0: cet objet est basé sur la spécification de schéma JSON 4 et en utilise un sous-ensemble prédéfini.

OpenAPI 3.0: Cet objet est un sous-ensemble étendu de la spécification de schéma JSON Wright Draft 00.

Si un service Web expose une date ou une date/heure non conforme au format de date/heure Internet décrit dans RFC3339 , alors date et date-heure ne sont pas des valeurs valides pour le format champ. La propriété doit être définie comme ayant un type égal à chaîne sans utiliser format . Au lieu de cela, motif peut être utilisé pour donner une expression régulière qui définit le motif de date ou date-heure. Cela permet à un outil client d'analyser automatiquement la date ou la date/heure.

Je recommande également de mettre le format dans le champ de description afin que les consommateurs puissent le lire plus facilement.

1
Kriil