Este dilema se puede abordar de diferentes formas, pero te compartimos la resolución más completa para nosotros.
Solución:
La especificación OpenAPI dice que debe usar:
escribe: string
formato: fecha # o fecha-hora
Los patrones admitidos se definen en RFC 3339, sección 5.6 (de hecho, ISO 8601) y se proporcionan ejemplos en la sección 5.8. Entonces para date los valores deben verse como “2018-03-20” y para date-time, “2018-03-20T09:12:28Z”. Como tal, al usar date o date-timela pattern es innecesario y, de hecho, debe omitirse.
Si necesita admitir fechas/horas formateadas de una manera diferente a RFC 3339, debe no permitido especificar su parámetro como format: date o format: date-time. En su lugar, debe especificar format: string con un apropiado pattern.
Finalmente, tenga en cuenta que un pattern de "YYYY-MM-DD" no es válido según la especificación: pattern debe ser un expresión regularno un marcador de posición o formato string.
Si está violando alguna de las reglas anteriores para evitar errores en herramientas que generan interfaces de usuario a partir de especificaciones de OpenAPI, debe considerar seriamente generar estos errores con esa herramienta, en lugar de generar una especificación de OpenAPI no válida para solucionar esto.
patrón debe ser una expresión regular. Esto se establece en la especificación OpenAPI.
patrón (Este string DEBERÍA ser una expresión regular válida, de acuerdo con el dialecto de expresión regular ECMA 262)
Esto se debe a que los objetos de OpenAPI se basan en la especificación del esquema JSON.
OpenAPI 2.0: este objeto se basa en el Borrador 4 de especificación de esquema JSON y utiliza un subconjunto predefinido del mismo.
OpenAPI 3.0: este objeto es un subconjunto ampliado de la especificación de esquema JSON Wright Draft 00.
Si un servicio web expone una fecha o una fecha y hora que no se ajusta al formato de fecha/hora de Internet descrito en RFC3339, entonces fecha y fecha y hora no son valores válidos para el formato campo. La propiedad debe definirse como que tiene una escribe igual a string sin uso formato. En cambio, patrón se puede usar para dar una expresión regular que define la fecha o el patrón de fecha y hora. Esto permite que una herramienta de cliente analice automáticamente la fecha o la fecha y hora.
También recomiendo poner el formato en el campo de descripción para que los consumidores humanos puedan leerlo más fácilmente.
Un ejemplo correcto de declaración de fecha en un archivo swagger de API abierta:
properties:
releaseDate:
type: date
pattern: /([0-9]4)-(?:[0-9]2)-([0-9]2)/
example: "2019-05-17"