Padrões e extensões do Swagger

Para facilitar a leitura e a interpretação dos contratos das APIs, este documento apresenta padrões e extensões do Swagger utilizados na definição dos campos e de seus comportamentos.

As extensões permitem adicionar propriedades personalizadas ao Swagger que não fazem parte da especificação nativa. Essas propriedades são identificadas pelo prefixo x-.

Referência: Swagger — Specification Extensions

1. Padrão Data/Hora

Descrição

Os campos de data e hora seguem o padrão UTC, utilizando o formato ISO 8601. Nesse formato, a letra T separa a data da hora, e a letra Z indica que o horário está em UTC.

Formatos aceitos:

  • YYYY-MM-DDTHH:MM:SSZ
  • YYYY-MM-DDTHH:MM:SS.MMMZ

Exemplos

Exemplo 1
text
1985-04-12T22:20:50Z
  • Brasil (UTC−3): 19:20:50
  • Portugal: 23:20:50 (considerando UTC+1)
Exemplo 2
text
2015-01-15T18:35:45.352Z
  • Brasil (UTC−3): 15:35:45.352
  • Egito: 20:35:45.352 (considerando UTC+2)

Comportamento nas operações HTTP

De acordo com o padrão descrito para as APIs:

  • GET: o cliente deverá subtrair do horário UTC a diferença correspondente ao fuso horário do país. Para o Brasil, considerando UTC−3, serão subtraídas 3 horas.
  • POST, PUT e PATCH: o cliente deverá adicionar ao horário informado a diferença correspondente ao fuso horário do país. Para o Brasil, considerando UTC−3, serão adicionadas 3 horas.

2. Padrão custom-date

Descrição

O formato custom-date permite representar datas em formatos personalizados, definidos pela expressão regular especificada na propriedade pattern.

Esse padrão pode ser utilizado, por exemplo, para datas de expiração de cartões, geralmente representadas por mês e ano.

Exemplo

yaml
Entidade: description: Descrição da entidade properties: codigo: type: string format: custom-date pattern: "^((0[1-9])|(1[0-2]))-([1-9]\\d{3})$" example: "09-2028" description: Descrição do campo.
No exemplo, o campo codigo aceita uma data no formato MM-YYYY, como 09-2028.

A expressão regular define que:

  • O mês deve estar entre 01 e 12.
  • O ano deve conter quatro dígitos, começando de 1 a 9.

3. Extensão x-used-write-method

Descrição

A extensão x-used-write-method define em quais métodos HTTP de escrita um campo da entidade pode ser utilizado, como POST, PUT e PATCH.

Exemplo

yaml
codigo: type: string x-used-write-method: - POST example: "C0001D" description: Descrição do campo.
No exemplo, o campo codigo poderá ser utilizado somente na operação POST.
Nas demais operações de escrita (PUT e PATCH), o campo deverá ser ignorado.

4. Extensão x-writeOnly

Descrição

A extensão x-writeOnly indica que um campo da entidade é destinado exclusivamente à escrita, nas operações POST, PUT e PATCH.

Exemplo

yaml
codigo: type: string x-writeOnly: true example: "C0001D" description: Descrição do campo.
No exemplo, o campo codigo poderá ser enviado nas operações POST, PUT e PATCH.
Na operação de leitura (GET), o campo deverá ser ignorado.

5. Extensão x-nullable

Descrição

A extensão x-nullable indica que um campo da entidade pode aceitar ou retornar o valor null, conforme o comportamento definido pela API.

Exemplo

yaml
codigo: type: string x-nullable: true example: null description: Descrição do campo.
No exemplo, o campo codigo poderá conter o valor null no retorno da API.

Resumo das extensões

PropriedadeFinalidade
custom-dateIdentifica campos de data em formatos personalizados, definidos por pattern.
x-used-write-methodDefine em quais métodos HTTP de escrita o campo poderá ser utilizado.
x-writeOnlyIndica que o campo é destinado exclusivamente às operações de escrita.
x-nullableIndica que o campo pode aceitar ou retornar null.
Observação: as regras funcionais descritas neste documento devem ser validadas conforme a implementação da API, especialmente a conversão de horários e o suporte às extensões personalizadas na versão do Swagger/OpenAPI utilizada.