OpenAPI vs GraphQL Schema: qual contrato?
OpenAPI descreve endpoints REST em um documento separado; um GraphQL schema é o sistema de tipos embutido e obrigatório que define uma API GraphQL.
OpenAPI é uma descrição opcional e externa de uma API REST - paths, métodos, parâmetros e formatos de resposta - que alimenta docs, codegen e validação. Um GraphQL schema é intrínseco à própria API: define cada tipo, query e mutation e é introspectável em runtime. OpenAPI documenta uma API REST que de outro modo é baseada em convenção; o GraphQL schema é o contrato da API por construção.
| OpenAPI | GraphQL Schema | |
|---|---|---|
| Relação | Descrição externa | Embutido na API |
| Opcional? | Sim (REST funciona sem) | Não (obrigatório) |
| Introspecção | Via o documento | Introspecção em runtime |
| Alimenta | Docs, codegen, mocks | Tipos, validação, codegen |
| Melhor para | Descrever REST | Definir GraphQL |
Como cada um define o contrato
Com REST você escolhe escrever OpenAPI para formalizar uma API que de outro modo é fracamente tipada, e precisa mantê-la em sincronia com a implementação. Com GraphQL o schema é o contrato da implementação e os clientes podem fazer introspecção dele diretamente. Ambos permitem tipagem forte e codegen, mas um é acoplado por fora enquanto o outro é inerente.
No CI
Pipelines de OpenAPI fazem lint da spec e checam se ela corresponde à implementação; pipelines de GraphQL validam o schema e protegem contra mudanças que quebram compatibilidade. Ambos rodam em managed runners, onde runners mais rápidos encurtam os passos de validação e codegen.
O veredito
Documentar e gerar ferramentas para uma API REST: OpenAPI. Definir um contrato de API fortemente tipado e introspectável por construção: um GraphQL schema. O ponto mais profundo é que o GraphQL embute o contrato, enquanto o REST precisa manter o OpenAPI ao lado dele.