Desenvolvimento
Modelo de documentação de API em Markdown
Uma boa documentação de API deixa um desenvolvedor fazer a primeira requisição bem-sucedida em minutos. Este modelo detalha um endpoint do início ao fim, para você copiar o padrão nos demais: visão geral, autenticação, parâmetros, um exemplo de requisição, campos de resposta, erros e um contato de suporte.
Abrir este modelo no editor- Categoria
- Desenvolvimento
- Estilo padrão
- Técnico
Quando usar
Use quando um parceiro, cliente ou time interno precisar de uma referência que possam ler off-line, anexar a um contrato ou guardar com um lançamento. Seus leitores são desenvolvedores que vão copiar da página, então o PDF mantém o texto selecionável e os exemplos de código mantêm a formatação.
O que tem dentro
- Seções de visão geral e autenticação, com campos para preencher projeto, responsável, data e e-mail de suporte.
- Um registro de endpoint com uma tabela de parâmetros mostrando tipo, se é obrigatório e descrição, além de um exemplo com curl.
- Uma tabela de campos de resposta e uma tabela de erros com status, significado e a ação a tomar.
Dicas para um documento melhor
- Use tokens de exemplo em cada trecho e nunca uma chave real. Indique a linguagem em cada bloco de código para que o MDPress aplique o realce de sintaxe.
- Quando documentar mais que alguns endpoints, ative o sumário com numeração de páginas para que os leitores pulem direto para o que precisam.
Pré-visualização do modelo
Referência da API de Projeto ou tema
Mantenedor: Seu nome · Atualizado em: Data
Visão geral
Explique o propósito da API, a URL base e a versão.
Autenticação
Descreva como obter um token e enviá-lo com segurança. Use valores fictícios nos exemplos.
Listar recursos
GET /v1/resources
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| limit | integer | Não | Número máximo de resultados por página |
| cursor | string | Não | Cursor retornado pela requisição anterior |
Exemplo de requisição
curl https://api.example.com/v1/resources
Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| data | array | Recursos retornados |
| next_cursor | string ou null | Token da próxima página |
Erros
| Status | Significado | Ação |
|---|---|---|
| 400 | Entrada inválida | Revisar os parâmetros |
| 401 | Autenticação necessária | Verificar as credenciais |
| 429 | Limite de requisições atingido | Respeitar a orientação de nova tentativa |
Suporte
Os campos de preenchimento, como seu nome e a data, são substituídos quando você abre o modelo no editor.