HomeCasa Prompts

Desenhar uma API REST com especificação OpenAPI

Desenhe uma API REST coerente: recursos, endpoints, códigos de estado, formato de erro, paginação, versionamento e um excerto OpenAPI 3.1. Pensado para ChatGPT, Claude e Gemini. Inclui 5 variáveis personalizáveis e pode copiá-lo gratuitamente com um clique.

Avançado · Código · Pendente de revisão editorial

Pensado para:

Prompt

Age como um arquiteto de APIs com experiência em desenhar APIs REST públicas utilizadas por terceiros.

Estou a construir a API de {{product}}.
Principais consumidores: {{consumers}}.
Entidades e relações conhecidas: {{entities}}.
Requisitos não funcionais: {{requirements}}.

Entrega, por esta ordem:
1. Modelo de recursos: a lista de recursos, os seus atributos principais, as relações e o identificador que cada um usa.
2. Tabela de endpoints (método, caminho, descrição, autenticação necessária, códigos de estado possíveis). Usa substantivos no plural, no máximo um nível de aninhamento e justifica qualquer ação que não seja CRUD.
3. Convenções: nomenclatura dos campos ({{naming_convention}}), datas ISO 8601 em UTC, paginação por cursor, filtragem, ordenação e campos parciais (sparse fieldsets).
4. Um único formato de erro baseado na RFC 9457 (Problem Details), com exemplos para 400, 401, 403, 404, 409, 422 e 429.
5. Estratégia de versionamento, idempotência (cabeçalho `Idempotency-Key` em POST) e controlo de concorrência (ETag / If-Match).
6. Segurança: esquema de autenticação, âmbitos de permissões e limites de pedidos.
7. Um excerto YAML OpenAPI 3.1 que cubra os dois recursos principais, os seus esquemas e respostas de erro reutilizáveis em `components`.
8. Riscos de desenho e decisões que vale a pena rever com a equipa.

Restrições:
- Não inventes regras de negócio: se algo não estiver claro, marca-o como [PREENCHER] e pergunta-me.
- Prefere a coerência à criatividade.

Como utilizar

  1. Liste as entidades que já conhece, mesmo que de forma aproximada.
  2. Diga quem vai consumir a API (aplicação móvel, parceiros, integrações internas).
  3. Reveja a tabela de endpoints antes de pedir a especificação OpenAPI completa.
  4. Importe o YAML no Swagger Editor ou no Stoplight para o validar.

Exemplo de utilização

Produto: plataforma de marcação de consultas para clínicas · Consumidores: aplicação móvel e parceiros · Entidades: clínica, profissional de saúde, utente, consulta.

Exemplo de resultado

2. Endpoints (excerto)

MétodoCaminhoDescriçãoAuthCódigos
GET/clinics/{clinic_id}/practitionersProfissionais de uma clínicaclinics:read200, 401, 404
POST/appointmentsCriar uma consultaappointments:write201, 409, 422
POST/appointments/{id}/cancelCancelar (ação não CRUD: mantém o histórico)appointments:write200, 409

7. OpenAPI 3.1 (excerto)

openapi: 3.1.0
info: { title: Clinic Booking API, version: 1.0.0 }
paths:
  /appointments:
    post:
      parameters:
        - { in: header, name: Idempotency-Key, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Appointment' }
      responses:
        '201': { description: Consulta criada }
        '409': { $ref: '#/components/responses/Problem' }
        '422': { $ref: '#/components/responses/Problem' }
components:
  schemas:
    Appointment:
      type: object
      required: [practitioner_id, patient_id, starts_at]
      properties:
        id: { type: string, readOnly: true }
        practitioner_id: { type: string }
        patient_id: { type: string }
        starts_at: { type: string, format: date-time }
  responses:
    Problem:
      description: Erro no formato RFC 9457
      content:
        application/problem+json:
          schema: { type: object, properties: { type: { type: string }, title: { type: string }, status: { type: integer }, detail: { type: string } } }

Os estados de uma consulta e a política de cancelamento são regras de negócio: [PREENCHER] antes de fechar o enum status…

Dados-chave

Categoria
Programação e desenvolvimento · APIs
Tipo de resultado
Código
Nível
Avançado
Pensado para
ChatGPT, Claude e Gemini
Verificado em
Pendente de verificação editorial
Variáveis
Produto, Consumidores, Entidades, Requisitos não funcionais e Convenção de nomenclatura
Idioma
Português
Preço
Gratuito, sem registo
Atualizado
07/11/2026

Perguntas frequentes

Paginação por cursor ou por página/offset?

Os cursores mantêm-se estáveis quando os dados mudam e escalam melhor em tabelas grandes. O offset é mais simples para ecrãs de administração internos que saltam para páginas concretas. O prompt usa cursores por omissão, mas pode pedir a alternativa.

Posso gerar código de servidor a partir da especificação OpenAPI?

Sim. Ferramentas como o OpenAPI Generator criam esqueletos de servidor e clientes em muitas linguagens. Complete e valide primeiro a especificação.

Para que serve este prompt?

Desenhe uma API REST coerente: recursos, endpoints, códigos de estado, formato de erro, paginação, versionamento e um excerto OpenAPI 3.1.

Com que ferramentas de IA funciona?

Foi pensado para ChatGPT, Claude e Gemini. Ainda não o verificámos nestas ferramentas, pelo que os resultados podem variar entre elas.

Como personalizo o prompt?

Clique em “Personalizar” e preencha as variáveis (Produto, Consumidores, Entidades, Requisitos não funcionais e Convenção de nomenclatura). O texto atualiza-se instantaneamente e pode depois copiá-lo com um clique. Os valores ficam guardados apenas no seu navegador.

Preciso de experiência para o utilizar?

É de nível avançado: destina-se a pessoas com experiência no tema, capazes de avaliar e ajustar o resultado.

Este prompt é gratuito?

Sim. Todos os prompts do HomeCasa Prompts são gratuitos, sem registo nem subscrição. Pode também utilizá-los em projetos profissionais.

Posso confiar no resultado da IA?

Trate-o como um rascunho de qualidade: verifique sempre os dados, os números e as afirmações importantes antes de publicar ou tomar decisões.

Prompts relacionados