OpenAPI (Swagger) Contract-First: A Verdade está no Contrato

Muitos times usam o Swagger apenas como uma “página bonitinha” que documenta a API depois que ela está pronta. Mas, o OpenAPI deve ser o ponto de partida: o Contract-First Development.

Integração

O time de Frontend e o time de Mobile estão parados esperando o Back-end terminar a API. Quando o Back-end termina, o JSON não é o que o Front esperava. Esse vai-e-vem custa caro.

O que é Contract-First?

Em vez de escrever o código e gerar o JSON do Swagger, você escreve o arquivo YAML/JSON do OpenAPI primeiro.

1. Acordo: Back, Front e Product Owners discutem o contrato antes de qualquer linha de código.
2. Paralelismo: Com o contrato definido, o Front pode criar um Mock Server (ex: Prism ou Stoplight) e começar a trabalhar imediatamente.
3. Geração de Código: Use ferramentas como o openapi-generator para gerar as Interfaces e DTOs automaticamente tanto no Java/Kotlin quanto no TypeScript.

Exemplo de Fluxo com Maven

Você coloca o arquivo api.yaml na pasta do projeto e o plugin do Maven gera as interfaces do Controller:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals><goal>generate</goal></goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <configOptions>
                    <interfaceOnly>true</interfaceOnly>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Vantagens

• Consistência: O código sempre reflete a documentação.
• Segurança: A validação de tipos e campos obrigatórios é feita automaticamente.
• Menos Boilerplate: Você não precisa escrever dezenas de DTOs manualmente; o gerador faz isso por você seguindo o padrão da indústria.

Takeaway prático

Se você quer implementar o Contract-First hoje, comece pequeno: defina o próximo endpoint da sua API no Swagger Editor antes de tocar no código do Controller. Compartilhe o YAML gerado com os consumidores da API e utilize uma ferramenta de mock para validar se o contrato atende às necessidades de todos. Esse pequeno investimento de tempo inicial evitará horas de refatoração e desalinhamento entre os times no futuro.