Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

The Response object's `default` field is confusing and inconsistently interpreted

Aberta
  • Algo errado?
#3,396 9 comentários 1 reação 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
28/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
openapi
Domínio
api, documentation

Direção de pesquisa

Comece revisando examples/v3.0/petstore-expanded.yaml e as definições do objeto Response para OpenAPI 3.0 e 3.1. Compare o significado documentado de default com o tratamento de erros pretendido pelo exemplo e, em seguida, identifique qual esclarecimento ou atualização do exemplo é viável; a conclusão exigiria uma alteração acordada na especificação ou nos exemplos.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

clarification re-use: globals/defaults

According both 3.0 and 3.1, in theResponse object there MUST be at least one response code and it SHOULD be the response for a successful operation call. In addition the default describes “responses other than the ones declared for specific HTTP response codes”.

This means that if we had a 200 response and default, the latter would cover everything except for 200. Many seem to interpret default to mean something like response categories not covered by explicit response codes. Consider this example from the OAI org:

responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml

This implies that default covers error types when in fact it covers non-error responses as well. In fact, the consumer wouldn't necessarily know if the API might reply with another success code such as a 204. A more precise example might look like this:

responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        4xx:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5xx:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

I would suggest the following actions:

  1. Update the example to interpret the spec more literally
  2. Clarify default since this confusion is not limited to this example, but extends to APIs in the wild
  3. Consider in 3.2 or 4.0 eliminating default
  4. Consider in 3.2 or 4.0 adding a new named error category that means "both 4xx and 5xx". This could be used in the way that default is often misused today
Linguagem predominante
Markdown
Estrelas
31.2k
Forks
9.2k
Merge médio
2d 9h
PRs com merge (30d)
17

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de OAI/OpenAPI-Specification

Todas as issues de OAI/OpenAPI-Specification

Issues semelhantes

Mais issues de Backend & API Design

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.