Como atualizar a documentação

Esta documentação é única e pública para todos os clientes. A referência de API é gerada automaticamente a partir das annotations @OA no código do projeto mkp-totem. Você nunca edita os endpoints à mão: edita a annotation no código, regenera o spec e rebuilda o site.

Visão geral do fluxo

Quem faz o quê

Papel	Responsabilidade
Desenvolvedor	Ao criar/alterar um endpoint, escreve o bloco @OA no controller (junto com o código). Valida com ./check.sh e commita. É o único passo manual de conteúdo.
CI / Operação (N2)	A publicação (gerar spec + buildar + subir o site) roda automaticamente no CI a cada push. Se não houver CI, o N2 executa o comando único de publicação (Passo 4).

O objetivo é que o desenvolvedor só precise escrever a annotation e commitar, sem o N2 ter que rodar nada na maioria das vezes.

Pré-requisitos

• Docker (para gerar o spec com PHP 7.2 e para servir o site).
• Node 20+ apenas se for rodar o site fora do Docker.

Validar antes de commitar (desenvolvedor)

Há um validador que compara as rotas em routes/web.php com as annotations @OA e avisa endpoints sem documentação, operationId duplicado e path divergente:

cd mkp-totem/docs/openapi
./check.sh

Modelo de annotation pronto para copiar: mkp-totem/docs/openapi/TEMPLATE.md.

Passo 1: editar a annotation no mkp-totem

Abra o controller do endpoint e edite o bloco @OA acima do método. Exemplo de um endpoint completo:

    /**
     * @OA\Post(
     *     path="/payment",
     *     operationId="payment_create",
     *     summary="Realiza o pagamento de um boleto",
     *     tags={"Agendamento"},
     *     security={{"bearerAuth":{}}},
     *     @OA\RequestBody(
     *       required=true,
     *       @OA\JsonContent(
     *         @OA\Property(property="bank_slip", type="string", example="2379..."),
     *         @OA\Property(property="amount", type="number", example=2.00),
     *       )
     *     ),
     *     @OA\Response(
     *       response=200, description="Sucesso",
     *       @OA\JsonContent(
     *         @OA\Property(property="data", type="object"),
     *         @OA\Property(property="msg", type="string", example="SUCCESS"),
     *         @OA\Property(property="statusCode", type="integer", example=200),
     *       )
     *     ),
     *     @OA\Response(response=400, description="Erro de negócio"),
     *     @OA\Response(response=401, description="Erro de validação"),
     *     @OA\Response(response=500, description="Erro interno")
     * )
     */
    public function payment(Request $request) { /* ... */ }

:::warning Regras importantes

• Edite somente o docblock @OA (comentário). Nunca altere o código do método.
• Documente todos os status que o método retorna e o corpo real de cada resposta (use @OA\JsonContent com as chaves reais).
• Textos em português, sem travessão (use : ou vírgula).
• Cada operationId deve ser único em todo o projeto. :::

Passo 2: regenerar o openapi.json

O spec é gerado dentro de um container PHP 7.2 isolado (não precisa instalar as dependências do projeto):

cd mkp-totem/docs/openapi
docker compose build        # apenas na primeira vez
docker compose run --rm openapi

O arquivo é gravado em mkp-totem/storage/api-docs/api-docs.json.

Valide o JSON:

python3 -c "import json; json.load(open('mkp-totem/storage/api-docs/api-docs.json')); print('OK')"

Passo 3: copiar o spec para o repositório de docs

cp mkp-totem/storage/api-docs/api-docs.json mkp-totem-docs/openapi.json

Passo 4: regenerar as páginas e rebuildar o site

cd mkp-totem-docs
npm run docusaurus clean-api-docs mkptotem   # limpa docs/api antigo
npm run docusaurus gen-api-docs mkptotem     # regenera docs/api do spec
docker compose up -d --build                 # rebuilda e sobe em :3000

Acesse http://localhost:3000 e confira o endpoint alterado.

Adicionar páginas de conteúdo (guias, fluxos)

• Conceitos: crie um .md em docs/concepts/ e adicione no sidebars.ts (sidebar docsSidebar).
• Fluxos: crie um .md em docs/flows/ com diagramas Mermaid e registre no sidebars.ts.

Diagramas Mermaid funcionam em qualquer .md:

```mermaid
sequenceDiagram
    participant POS
    participant PSI
    POS->>PSI: Solicita pagamento
    PSI-->>POS: Retorna QR Code
```

Traduções da interface

Os rótulos da interface (Requisição, Respostas, etc.) ficam em i18n/pt-BR/code.json. Para adicionar novos termos do tema, edite esse arquivo (chaves theme.openapi.*).

Controle de acesso (autenticação)

O site é protegido por HTTP Basic Auth via nginx (acesso restrito por cliente). As credenciais ficam em nginx/.htpasswd, um par usuário/senha por linha.

Adicionar ou alterar um usuário

cd mkp-totem-docs
# adiciona/atualiza o usuário "cliente_novo"
docker run --rm httpd:2.4-alpine htpasswd -nbB cliente_novo "senhaForte" >> nginx/.htpasswd
# remova linhas em branco, se houver
grep -v '^$' nginx/.htpasswd > nginx/.htpasswd.tmp && mv nginx/.htpasswd.tmp nginx/.htpasswd
docker compose up -d   # recarrega o nginx

Remover um usuário

Edite nginx/.htpasswd e apague a linha do usuário, depois docker compose up -d.

Como funciona

Cliente ──(usuário/senha)──► nginx (Basic Auth) ──► site Docusaurus (interno :3000)

O serviço docs não é exposto diretamente; só o auth (nginx) publica a porta 3000. Sem credencial válida, o nginx responde 401.

Deploy no AWS

A mesma composição funciona no AWS:

• ECS/EC2: suba os dois containers (docs + auth) como estão. O auth (nginx) é o ponto de entrada.
• CloudFront + Lambda@Edge: para site estático em S3, valide o Basic Auth no Lambda@Edge (mesma lógica de usuário/senha).
• AWS Amplify: use o Access Control nativo do Amplify (senha por ambiente).
• ALB + Cognito: para login completo com SSO/MFA, integre o Application Load Balancer com o Cognito.

Publicação

Em produção, o site é um container que builda e serve a pasta estática:

cd mkp-totem-docs
docker compose up -d --build

Para hospedagem pública, qualquer serviço de site estático funciona (o build/ gerado por npm run build é 100% estático). Aponte o domínio público para esse build. Todos os clientes consomem a mesma URL.

Checklist de atualização

• Annotation @OA editada no controller correto (mkp-totem)
• php -l sem erros no controller alterado
• docker compose run --rm openapi executado (spec regenerado)
• openapi.json copiado para mkp-totem-docs
• gen-api-docs executado
• Site rebuildado (docker compose up -d --build)
• Endpoint conferido em http://localhost:3000