Skip to content

Commit db1842d

Browse files
jrCleberjrCleber
committed
Initialize CodeChat API documentation
0 parents  commit db1842d

133 files changed

Lines changed: 32753 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.dockerignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.git
2+
.github
3+
.next
4+
node_modules
5+
.codex-dev.*.log
6+
coverage
7+
playwright-report
8+
test-results
9+
npm-debug.log*
10+
pnpm-debug.log*

‎.env.example‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
NEXT_PUBLIC_SITE_URL=http://localhost:3000
2+
NEXT_PUBLIC_CODECHAT_API_URL=http://localhost:8084
3+
NEXT_PUBLIC_GITHUB_URL=https://github.com/jrCleber/whatsapp-api-go
4+
NEXT_PUBLIC_SUPPORT_URL=https://github.com/jrCleber/whatsapp-api-go/issues
5+
NEXT_PUBLIC_DOCS_TITLE=CodeChat API
6+
NEXT_PUBLIC_DOCS_VERSION=1.0.0
7+
NEXT_PUBLIC_OPENAPI_URL=/openapi.yml
8+
NEXT_PUBLIC_POSTMAN_URL=https://www.postman.com/codechat/codechat-api/collection/1yi47fy/go-v1-0-0
9+
10+
# Aliases aceitos pelo docker-compose para compatibilidade com o contrato solicitado.
11+
VITE_API_BASE_URL=http://localhost:8084
12+
VITE_DOCS_TITLE=CodeChat API
13+
VITE_DOCS_VERSION=1.0.0
14+
VITE_GITHUB_URL=https://github.com/jrCleber/whatsapp-api-go
15+
VITE_OPENAPI_URL=/openapi.yml
16+
VITE_API_POSTMAN=https://www.postman.com/codechat/codechat-api/collection/1yi47fy/go-v1-0-0
17+
18+
# Caminho absoluto ou relativo até a pasta docs do whatsapp-go-api.
19+
CODECHAT_SOURCE_DOCS=./openapi.yml

‎.github/workflows/ci.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Portal checks
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
11+
env:
12+
SOURCE_REPOSITORY: jrCleber/whatsapp-api-go
13+
CODECHAT_SOURCE_DOCS: ../whatsapp-go-api/docs
14+
NEXT_PUBLIC_SITE_URL: http://localhost:3000
15+
NEXT_PUBLIC_CODECHAT_API_URL: http://localhost:8084
16+
17+
jobs:
18+
validate:
19+
runs-on: ubuntu-latest
20+
timeout-minutes: 25
21+
steps:
22+
- name: Checkout portal
23+
uses: actions/checkout@v4
24+
25+
- name: Checkout API source of truth
26+
run: git clone --depth 1 "https://github.com/${SOURCE_REPOSITORY}.git" ../whatsapp-go-api
27+
28+
- name: Install pnpm
29+
uses: pnpm/action-setup@v4
30+
with:
31+
version: 11.12.0
32+
run_install: false
33+
34+
- name: Set up Node.js
35+
uses: actions/setup-node@v4
36+
with:
37+
node-version: 22
38+
cache: pnpm
39+
40+
- name: Install dependencies
41+
run: pnpm install --frozen-lockfile
42+
43+
- name: Synchronize source documentation
44+
run: pnpm sync:docs
45+
46+
- name: Generate webhook catalog and audit route parity
47+
run: pnpm generate:webhooks && pnpm audit:api
48+
49+
- name: Lint
50+
run: pnpm lint
51+
52+
- name: Typecheck
53+
run: pnpm typecheck
54+
55+
- name: Validate OpenAPI
56+
run: pnpm validate:openapi
57+
58+
- name: Unit and component tests
59+
run: pnpm test
60+
61+
- name: Build
62+
run: pnpm build
63+
64+
- name: Install Playwright Chromium
65+
run: pnpm exec playwright install --with-deps chromium
66+
67+
- name: End-to-end tests
68+
run: pnpm test:e2e

‎.gitignore‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# deps
2+
/node_modules
3+
4+
# generated content
5+
.source
6+
7+
# test & build
8+
/coverage
9+
/.next/
10+
/out/
11+
/build
12+
/coverage
13+
/playwright-report
14+
/test-results
15+
*.tsbuildinfo
16+
17+
# misc
18+
.DS_Store
19+
*.pem
20+
/.env
21+
/.pnp
22+
.pnp.js
23+
npm-debug.log*
24+
yarn-debug.log*
25+
yarn-error.log*
26+
27+
# others
28+
.env*.local
29+
.vercel
30+
next-env.d.ts
31+
.codex-dev.*.log

‎.prettierignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.next
2+
.source
3+
content
4+
docs
5+
node_modules
6+
public
7+
openapi.yml
8+
pnpm-lock.yaml
9+
test-results
10+
playwright-report
11+
coverage

‎.prettierrc.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"printWidth": 120,
3+
"singleQuote": true,
4+
"trailingComma": "all"
5+
}

‎Dockerfile‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# syntax=docker/dockerfile:1.7
2+
FROM node:22-alpine AS dependencies
3+
WORKDIR /app
4+
RUN corepack enable
5+
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
6+
RUN pnpm install --frozen-lockfile --ignore-scripts
7+
8+
FROM node:22-alpine AS builder
9+
WORKDIR /app
10+
RUN corepack enable
11+
COPY --from=dependencies /app/node_modules ./node_modules
12+
COPY . .
13+
RUN pnpm rebuild && pnpm postinstall
14+
ARG NEXT_PUBLIC_SITE_URL=http://localhost:3000
15+
ARG NEXT_PUBLIC_CODECHAT_API_URL=http://localhost:8084
16+
ARG NEXT_PUBLIC_GITHUB_URL=https://github.com/jrCleber/whatsapp-api-go
17+
ARG NEXT_PUBLIC_SUPPORT_URL=https://github.com/jrCleber/whatsapp-api-go/issues
18+
ARG NEXT_PUBLIC_DOCS_TITLE=CodeChat API
19+
ARG NEXT_PUBLIC_DOCS_VERSION=1.0.0
20+
ARG NEXT_PUBLIC_OPENAPI_URL=/openapi.yml
21+
ARG NEXT_PUBLIC_POSTMAN_URL=https://www.postman.com/codechat/codechat-api/collection/1yi47fy/go-v1-0-0
22+
ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
23+
ENV NEXT_PUBLIC_CODECHAT_API_URL=$NEXT_PUBLIC_CODECHAT_API_URL
24+
ENV NEXT_PUBLIC_GITHUB_URL=$NEXT_PUBLIC_GITHUB_URL
25+
ENV NEXT_PUBLIC_SUPPORT_URL=$NEXT_PUBLIC_SUPPORT_URL
26+
ENV NEXT_PUBLIC_DOCS_TITLE=$NEXT_PUBLIC_DOCS_TITLE
27+
ENV NEXT_PUBLIC_DOCS_VERSION=$NEXT_PUBLIC_DOCS_VERSION
28+
ENV NEXT_PUBLIC_OPENAPI_URL=$NEXT_PUBLIC_OPENAPI_URL
29+
ENV NEXT_PUBLIC_POSTMAN_URL=$NEXT_PUBLIC_POSTMAN_URL
30+
ENV CODECHAT_SKIP_SYNC=1
31+
ENV CODECHAT_SKIP_AUDIT=1
32+
ENV NEXT_OUTPUT_STANDALONE=1
33+
RUN pnpm build
34+
35+
FROM node:22-alpine AS runner
36+
WORKDIR /app
37+
ENV NODE_ENV=production
38+
ENV HOSTNAME=0.0.0.0
39+
ENV PORT=3000
40+
RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
41+
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
42+
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
43+
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
44+
USER nextjs
45+
EXPOSE 3000
46+
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD node -e "fetch('http://127.0.0.1:3000/api-reference').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
47+
CMD ["node", "server.js"]

‎README.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# CodeChat API Docs
2+
3+
Portal oficial de documentação e referência técnica da CodeChat. Guias editoriais e referência OpenAPI compartilham o mesmo `DocumentationShell`, mantendo uma única topbar, sidebar, base tipográfica, painel contextual, tema e comportamento responsivo. O conteúdo editorial continua em MDX e é sincronizado da pasta `docs` do repositório da API.
4+
5+
## O que está incluído
6+
7+
- Referência dinâmica de 95 operações HTTP, agrupadas pelas tags do OpenAPI.
8+
- URLs compartilháveis baseadas em `operationId`.
9+
- Layout técnico de três colunas centralizado em até 1680 px, tema escuro/claro, sidebar recolhível e navegação mobile.
10+
- Autenticação, parâmetros, request body, schemas, respostas por status e exemplos JSON.
11+
- Exemplos gerados em cURL, JavaScript, Node.js/Axios, Go, Python e PHP.
12+
- Acesso direto à coleção oficial `Go v1.0.0` no Postman.
13+
- Playground no navegador com cancelamento, timeout, resultado formatado e credenciais mascaradas.
14+
- Busca global por endpoint, rota, método, parâmetro, schema e evento (`Ctrl/Cmd + K`).
15+
- Catálogo de 41 webhooks reais: 27 por instância e 14 globais de Message Batch.
16+
- Guias editoriais existentes, changelog, migração e explicação explícita da ausência de WebSocket/SSE.
17+
18+
O relatório completo de paridade entre runtime e contrato fica em [`docs/api-reference-audit.md`](docs/api-reference-audit.md).
19+
20+
## Capturas de tela
21+
22+
As capturas finais de desktop e mobile podem ser adicionadas em `public/screenshots/` após a publicação no ambiente definitivo.
23+
24+
## Tecnologias e decisões
25+
26+
O projeto já existia como portal Next.js; por isso ele foi evoluído em vez de criar um segundo frontend ou remover a documentação atual. A base usa Next.js 16, React 19, TypeScript strict, Tailwind CSS 4, Fumadocs/MDX, Prism, Lucide, Zod, `openapi-types`, YAML, Vitest, Testing Library e Playwright.
27+
28+
O OpenAPI é a fonte única da referência HTTP. Componentes React não contêm listas manuais de endpoints. Regras editoriais como ordem de tags, aliases e flags experimentais ficam centralizadas em `src/config/documentation.ts`. O documento é lido e normalizado uma única vez por processo e as páginas são divididas por rota.
29+
30+
## Estrutura principal
31+
32+
```text
33+
src/
34+
app/api-reference/ rotas da referência e estilos responsivos
35+
components/api/ endpoint, schemas, respostas e playground
36+
components/layout/ DocumentationShell, topbar, sidebar e painel contextual
37+
components/common/ código, cópia e estados reutilizáveis
38+
features/openapi/ loader, normalização, exemplos e code samples
39+
features/playground/ montagem segura de requisições
40+
features/search/ ranking do índice global
41+
config/ branding e ordem documental
42+
content/docs/ conteúdo MDX sincronizado e guias locais
43+
public/openapi.yml cópia sincronizada servida pelo portal
44+
public/webhook-events.json catálogo gerado de eventos
45+
scripts/ sync, auditoria, validação e índices
46+
tests/ testes unitários, componentes e E2E
47+
```
48+
49+
## Pré-requisitos
50+
51+
- Node.js 22 ou superior;
52+
- pnpm 11.12;
53+
- repositório `whatsapp-go-api` no diretório irmão, ou `CODECHAT_SOURCE_DOCS` apontando para sua pasta `docs`.
54+
55+
## Desenvolvimento
56+
57+
```bash
58+
pnpm install
59+
cp .env.example .env
60+
pnpm dev
61+
```
62+
63+
O portal abre em `http://localhost:3000`. Antes do desenvolvimento, a documentação fonte, o catálogo de webhooks e o índice de busca são atualizados automaticamente.
64+
65+
Comandos úteis:
66+
67+
```bash
68+
pnpm sync:docs
69+
pnpm audit:api
70+
pnpm validate:openapi
71+
pnpm generate:search-index
72+
pnpm lint
73+
pnpm typecheck
74+
pnpm test
75+
pnpm test:e2e
76+
pnpm build
77+
pnpm start
78+
```
79+
80+
`pnpm check` executa lint, typecheck, testes unitários e build.
81+
82+
## Variáveis de ambiente
83+
84+
| Variável | Finalidade | Padrão |
85+
| ------------------------------ | --------------------------------------- | ------------------------- |
86+
| `NEXT_PUBLIC_SITE_URL` | URL pública do portal | `http://localhost:3000` |
87+
| `NEXT_PUBLIC_CODECHAT_API_URL` | Base URL usada em exemplos e playground | `http://localhost:8084` |
88+
| `NEXT_PUBLIC_DOCS_TITLE` | Título do portal | `CodeChat API` |
89+
| `NEXT_PUBLIC_DOCS_VERSION` | Versão exibida | `1.0.0` |
90+
| `NEXT_PUBLIC_GITHUB_URL` | Link do repositório | repositório da API |
91+
| `NEXT_PUBLIC_OPENAPI_URL` | Caminho ou URL absoluta do OpenAPI | `/openapi.yml` |
92+
| `NEXT_PUBLIC_POSTMAN_URL` | Coleção oficial da CodeChat no Postman | coleção `Go v1.0.0` |
93+
| `CODECHAT_SOURCE_DOCS` | Pasta de documentação da API | `../whatsapp-go-api/docs` |
94+
95+
O `docker-compose.yml` também aceita os aliases solicitados `VITE_API_BASE_URL`, `VITE_DOCS_TITLE`, `VITE_DOCS_VERSION`, `VITE_GITHUB_URL`, `VITE_OPENAPI_URL` e `VITE_API_POSTMAN`, mapeando-os para as variáveis públicas do Next.js. Essas variáveis são aplicadas em build time; é necessário reconstruir a imagem ao alterá-las.
96+
97+
## OpenAPI e manutenção
98+
99+
A fonte canônica é `../whatsapp-go-api/docs/openapi.yml`. Não edite apenas a cópia em `public/`.
100+
101+
Para documentar um endpoint:
102+
103+
1. confirme a rota, middleware, DTO, validações e respostas no código Go;
104+
2. atualize o path existente na especificação canônica, incluindo `operationId`, tag, security e exemplos;
105+
3. execute `pnpm sync:docs && pnpm audit:api && pnpm validate:openapi`;
106+
4. use `src/config/documentation.ts` somente para ordem, aliases ou metadados editoriais — nunca para duplicar a operação.
107+
108+
Para adicionar uma categoria, declare a tag no OpenAPI e inclua seu nome em `tagOrder`. Exemplos explícitos em `content`/`schema` têm prioridade; na ausência deles, o gerador respeita tipo, enum, formato, default e referências recursivas.
109+
110+
## Playground e segurança
111+
112+
As requisições são executadas diretamente pelo navegador contra a Base URL, sem serviço intermediário. A API precisa liberar a origem do portal no CORS. Tokens não são enviados a terceiros nem registrados no console. A sessão usa `sessionStorage` por padrão; `localStorage` só é ativado por escolha explícita.
113+
114+
Não existe proxy remoto inseguro. Um proxy local pode ser configurado por quem desenvolve, mas não faz parte da configuração de produção.
115+
116+
## Docker e produção
117+
118+
O Dockerfile usa múltiplos estágios e produz o servidor standalone do Next.js. O Compose adiciona Nginx com gzip, cache longo apenas para assets versionados, ausência de cache agressivo no OpenAPI, SPA/reverse-proxy fallback e healthchecks.
119+
120+
O build da imagem reutiliza o OpenAPI sincronizado e o relatório de auditoria já versionados, pois o repositório irmão da API fica fora do contexto Docker. A auditoria contra o código Go continua obrigatória no desenvolvimento e no CI antes de produzir a imagem.
121+
122+
```bash
123+
docker compose up --build -d
124+
curl http://localhost:3000/healthz
125+
```
126+
127+
Para outra porta, use `DOCS_PORT=8080 docker compose up --build -d`. Sem Compose:
128+
129+
```bash
130+
docker build -t codechat-api-docs .
131+
docker run --rm -p 3000:3000 codechat-api-docs
132+
```
133+
134+
## Testes e CI
135+
136+
- Vitest valida normalização, `$ref`, schemas recursivos, exemplos, busca, cURL, request builder e tabs de resposta.
137+
- Playwright valida navegação da sidebar, busca por teclado, playground e ausência de overflow no mobile.
138+
- A auditoria falha quando uma rota registrada não está no OpenAPI ou quando o OpenAPI contém rota inexistente.
139+
- O CI sincroniza o repositório fonte e executa lint, typecheck, testes, validação OpenAPI e build.
140+
141+
## Publicação
142+
143+
Publique a imagem gerada pelo Dockerfile ou o servidor standalone atrás do Nginx fornecido. Preserve `public/openapi.yml` e `public/webhook-events.json` no artefato. Depois do deploy, confirme `/healthz`, uma URL de endpoint como `/api-reference/listInstances`, busca, playground/CORS e os viewports desktop e mobile.

‎content/docs/auth-reference.mdx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: "Referência de autenticação"
3+
description: "Resumo operacional dos dois esquemas de segurança do OpenAPI."
4+
---
5+
6+
## `GlobalApiKey`
7+
8+
Envie `apikey: $GLOBAL_TOKEN` em `POST /instance`, `GET /instance` e nas nove operações `/message/batches...`. Os aliases `x-api-key` e `apiKey` também são aceitos; se mais de um for enviado, todos precisam ter exatamente o mesmo valor.
9+
10+
## `InstanceBearer`
11+
12+
Envie `Authorization: Bearer $INSTANCE_TOKEN` nas operações da instância. O JWT usa HS256 e contém `instanceName`, comparado com o nome da rota.
13+
14+
## Referência interativa
15+
16+
A [referência própria da CodeChat](/api-reference) lê os dois esquemas diretamente do OpenAPI. Credenciais são enviadas somente para a Base URL escolhida. O playground usa `sessionStorage` por padrão e só usa `localStorage` quando a pessoa marca explicitamente a opção de persistência; o portal não usa proxy externo.

0 commit comments

Comments
 (0)