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

Consider additional guidance on Server Objects

Aberta
  • Algo errado?
#4,542 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
35/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
openapi
Domínio
documentation

Direção de pesquisa

Comece pela página Server Object do Learn Site e revise as preocupações levantadas na PR #4389, especialmente as observações sobre URLs de servidor relativas, URIs de recuperação e variáveis de servidor. Considera-se concluído quando for decidido onde esta orientação deve ficar e as ressalvas relevantes forem documentadas claramente, seja no Learn Site ou na documentação da especificação.

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

Descrição

deployment

@karenetheridge and @notEthan raised various points about confusion and usage of the Server Object and its url field in PR #4389.

From @karenetheridge

We can also offer caution that if server urls are not absolute, then the retrieval URI will be used to resolve them, which might not be desirable because if the scheme+host of the retrieval URI may not actually be the same scheme+host as where the APIs are being hosted, the result will be that any matching of API HTTP requests against path-items in the OpenAPI document will fail.

This caveat is not new with these changes, but a user might think that an absolute $self is sufficient to ward off this problem, which it isn't.

From @notEthan (the part about server variables vs relative server URLs being the most relevant to this issue, see #4541 for other concerns raised in this quote):

I certainly agree/understand that the URIs of the API description and objects within are quite different than (or unrelated to) API server/endpoint URLs. My hesitation is on the idea that the retrieval URI for the OAD is likely to be more closely related to the server URL than $self (I've generally seen the OAD served from one place accompanying documentation, not with each deployment, and aren't server variables the better mechanism for deployment-specific URLs?).

Or rather, my hesitation as an implementer of tooling is on whether that difference is worth implementing - I have one base URI for objects in the OAD (including servers), which will be changing to inherit from $self, and no place to put another base URI. It's not difficult to implement but it adds some complexity in a place I have doubts on the real utility of it.

Note that some of this guidance could go on the Learn Site, which already has a substantial page on the Server Object.

Linguagem predominante
Markdown
Estrelas
31.3k
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 Documentation

Receba novas issues na sua caixa de entrada

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