Aula 5 - Módulo 6: Documentação automática e design de APIs enterprise
Documentação clara e automática permite que equipes frontend e backend trabalhem independentemente, reduzindo dependências e acelerando desenvolvimento.
Contratos versionados e documentação automática garantem que mudanças na API sejam comunicadas e gerenciadas sem quebrar integrações existentes.
Novos desenvolvedores conseguem entender e usar a API rapidamente com documentação interativa e exemplos de código atualizados.
Documentação gerada a partir dos tipos TypeScript garante sincronização perfeita entre implementação e especificação.
Auto-generation:
Documentação gerada automaticamente do código
OpenAPI Spec:
Especificação padrão para APIs REST
Interactive Docs:
Documentação que permite testar a API
Versioning:
Gestão de mudanças e compatibilidade
// 📁 scripts/generate-docs.ts
import { Application, TSConfigReader } from 'typedoc';
const app = new Application();
app.options.addReader(new TSConfigReader());
app.bootstrap({
entryPoints: ['src/server/api/root.ts'],
out: 'docs/api',
theme: 'default',
includeVersion: true,
excludeExternals: true,
plugin: ['typedoc-plugin-markdown']
});
const project = app.convert();
if (project) {
await app.generateDocs(project, 'docs/api');
console.log('📚 API documentation generated');
}// 📁 server/openapi/generator.ts
import { generateOpenApiDocument } from 'trpc-openapi';
import { appRouter } from '@/server/api/root';
export const openApiDocument = generateOpenApiDocument(appRouter, {
title: 'tRPC API',
description: 'An API for awesome things',
version: '1.0.0',
baseUrl: 'https://api.example.com',
docsUrl: 'https://api.example.com/docs',
tags: ['Users', 'Posts', 'Comments']
});
// Serve OpenAPI JSON
export function createOpenAPIHandler() {
return (req: Request, res: Response) => {
res.setHeader('Content-Type', 'application/json');
res.send(openApiDocument);
};
}// 📁 contracts/api-contracts.ts
import { z } from 'zod';
export const UserContract = {
getById: {
input: z.object({ id: z.string().uuid() }),
output: z.object({
id: z.string(),
name: z.string(),
email: z.string().email(),
createdAt: z.date()
})
},
create: {
input: z.object({
name: z.string().min(2),
email: z.string().email(),
password: z.string().min(8)
}),
output: z.object({
id: z.string(),
name: z.string(),
email: z.string()
})
}
};// 📁 docs/components/ApiPlayground.tsx
import { useState } from 'react';
import { trpc } from '@/utils/trpc';
export function ApiPlayground() {
const [userId, setUserId] = useState('');
const { data, isLoading, error } = trpc.user.getById.useQuery(
{ id: userId },
{ enabled: !!userId }
);
return (
<div className="api-playground">
<h3>Try the API</h3>
<input
value={userId}
onChange={(e) => setUserId(e.target.value)}
placeholder="Enter user ID"
/>
{isLoading && <p>Loading...</p>}
{error && <p>Error: {error.message}</p>}
{data && <pre>{JSON.stringify(data, null, 2)}</pre>}
</div>
);
}Parabéns! Você domina ferramentas enterprise para tRPC e está pronto para liderar projetos de grande escala com qualidade profissional!