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

[Schema Inaccuracy] "contents" endpoints response seem way under-specified

Aberta
  • Algo errado?
#650 4 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
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
38/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
openapi, yaml
Domínio
api

Direção de pesquisa

Comece pelos schemas file-commit e content-file descritos na issue e, em seguida, compare-os com as respostas dos endpoints PUT e DELETE contents. Determine quais propriedades estão presentes de forma consistente, se content é nullable apenas para DELETE e se type deve ser restringido. Considera-se concluído quando os schemas OpenAPI descreverem corretamente ambas as variantes de resposta e seus campos obrigatórios.

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

Descrição

feature fundamentals-and-support P4 shield waiting for review

The "updating "contents" endpoints (PUT, or DELETE on /repos/{owner}/{repo}/contents/{path}, but not GET) all respond with a file-commit defined thus:

    file-commit:
      title: File Commit
      description: File Commit
      type: object
      required:
      - content
      - commit
      properties:
        content:
          type: object
          properties:
            name:
              type: string
            path:
              type: string
            sha:
              type: string
            size:
              type: integer
            url:
              type: string
            html_url:
              type: string
            git_url:
              type: string
            download_url:
              type: string
            type:
              type: string
            _links:
              type: object
              properties:
                self:
                  type: string
                git:
                  type: string
                html:
                  type: string
          nullable: true
        commit:
          type: object
          properties:
            sha:
              type: string
            node_id:
              type: string
            url:
              type: string
            html_url:
              type: string
            author:
              type: object
              properties:
                date:
                  type: string
                name:
                  type: string
                email:
                  type: string
            committer:
              type: object
              properties:
                date:
                  type: string
                name:
                  type: string
                email:
                  type: string
            message:
              type: string
            tree:
              type: object
              properties:
                url:
                  type: string
                sha:
                  type: string
            parents:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                  html_url:
                    type: string
                  sha:
                    type: string
            verification:
              type: object
              properties:
                verified:
                  type: boolean
                reason:
                  type: string
                signature:
                  type: string
                  nullable: true
                payload:
                  type: string
                  nullable: true

So file-commit has two required properties content and commit, with the first being nullable.

It's my understanding that content is null in the case of DELETE, in the case of PUT it's present and contains the information of the just-created file.

However I don't understand in what case all the properties of a non-null content or a commit would be missing, surely most or all properties should be required, with the possible (probable?) exception of commit.verification?

All in all, file-commit.content looks like a slightly cut down version of content-file (without encoding and content), so probably should otherwise have the same schema? And for both it seems like the type field should be an enum with file as the only option?

I think file-commit.content could be something like a file type with content-file being an allOf(file, {encoding: ..., content: ...}) but I guess that increases the complexity of the schema and currently there's a single use site for allOf so that's probably a tad too much.

Linguagem predominante
Sem dados de linguagem
Estrelas
1.6k
Forks
347
Merge médio
2h 1min
PRs com merge (30d)
80

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 github/rest-api-description

Todas as issues de github/rest-api-description

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.