social-products-openapi-documenter

Gera documentação OpenAPI 3 a partir dos blocos documentation do serverless.yml.

Substitui o serverless-openapi-documenter (desatualizado) sem exigir mudança nos YAMLs existentes: o schema de entrada é o mesmo usado por serverless-aws-documentation e serverless-openapi-documenter.

• 1 dependência de runtime (js-yaml). Nada de swagger-parser/json-schema-ref-parser, que é justamente a cadeia que envelhece nesse tipo de plugin.
• Duas formas de uso: plugin do Serverless Framework v4 (sls openapi generate) e binário standalone (sp-openapi), que lê os YAMLs direto — roda em CI sem credenciais AWS, sem org/app e sem licença do Serverless.
• Validador embutido que aponta o problema no YAML de origem, não no JSON gerado.
• Saída em YAML, JSON ou HTML (página Swagger UI autocontida).

Instalação

npm i -D social-products-openapi-documenter

Uso como plugin do Serverless

# serverless.yml
plugins:
  - social-products-openapi-documenter

custom: ${file(serverless/custom.yml)}

functions: ${file(serverless/routes/ms-oficinas-route.yml)}

npx serverless openapi generate --out openapi.yml --stage dev

Opções: --out/-o, --format/-f (yaml|json|html), --indent, --no-validate, --fail-on-warning, --openapi-version.

Aqui as variáveis (${file(...)}, ${param:...}, ${env:...}) já chegam resolvidas pelo próprio framework.

Uso como CLI standalone

Para testar sem tocar em nenhum projeto, use o serviço de exemplo em example/: node dist/cli.js generate -c example -o example/openapi.yml --stage dev

npx sp-openapi generate -o openapi.yml --stage dev
npx sp-openapi generate -o docs/openapi.json -f json --stage prod
npx sp-openapi generate -o docs/index.html --param COGNITO_POOL_ID=abc

-c, --config <path>     serverless.yml ou diretório do serviço (default: cwd)
-o, --out <path>        arquivo de saída (default: openapi.yml)
-f, --format <fmt>      yaml | json | html (default: pela extensão de --out)
    --indent <n>        indentação da saída (default: 2)
-s, --stage <stage>     valor de ${opt:stage} e ${sls:stage} (default: dev)
    --region <region>   valor de ${aws:region}
    --account-id <id>   valor de ${aws:accountId}
    --param <k=v>       valor de ${param:k} (repetível)
    --no-validate       não valida o documento gerado
    --fail-on-warning   sai com código 1 também em caso de warning
-q, --quiet             imprime apenas erros

O CLI resolve por conta própria ${file(...)} (com :chave.aninhada), ${self:...}, ${opt:...}, ${env:...}, ${param:...}, ${sls:...}, ${aws:...}, cadeias de fallback (${param:A, env:B, 'default'}) e interpolação aninhada (${self:custom.MEMORY_SIZE.${self:provider.stage}}).

Fontes que exigem chamada à AWS (${ssm:...}, ${cf:...}, ${s3:...}, ${secretsmanager:...}) não são resolvidas: a variável é mantida literal e um warning é emitido — gerar documentação não deveria depender de credenciais. Se alguma dessas variáveis afeta o bloco documentation, use o plugin em vez do CLI.

Em CI

- run: npx sp-openapi generate -o openapi.yml --stage dev --fail-on-warning
- run: git diff --exit-code openapi.yml   # falha se a doc estiver desatualizada

Uso como biblioteca

import { generateOpenApi, loadServerlessConfig } from 'social-products-openapi-documenter';

const service = loadServerlessConfig({ config: '.', stage: 'dev' });
const { document, issues } = generateOpenApi({
  documentation: service.documentation,
  functions: service.functions,
});

Formato de entrada

custom.documentation

Idêntico ao dos plugins antigos:

# serverless/docs/openapi/serverless.doc.yml
documentation:
  version: '1'
  title: 'ms-oficinas API'
  models:
    - name: GetHealthModel
      contentType: "application/json"
      schema: ${file(serverless/docs/openapi/models/GetHealthModel.json)}
  tags:
    - name: "Evaluation"
      description: Evaluation routes

# serverless/custom.yml
documentation: ${file(serverless/docs/openapi/serverless.doc.yml):documentation}

models também aceita mapa (GetHealthModel: { schema: ... }) e o alias modelsList. O bloco pode ficar em custom.documentation ou na raiz do serverless.yml.

documentation no evento http

getOneEvaluation:
  handler: ./src/evaluation-handler.evaluationOne
  events:
    - http:
        path: /workshop/v1/evaluations/{evaluation_id}
        method: GET
        cors: ${file(serverless/cors.yml)}
        documentation:
          summary: Retorna uma avaliação específica
          description: Lista uma avaliação.
          tags:
            - Evaluation
          pathParams:
            - name: evaluation_id
              description: Id da avaliação
              required: true
              schema:
                type: string
          queryParams:
            - name: active
              required: false
              schema:
                type: boolean
          headerParams:
            - name: "x-api-role"
              description: "Token de usuário"
              schema:
                type: "string"
          requestBody:
            description: "requisição de avaliação"
          requestModels:
            application/json: "PostEvaluationRequest"
          methodResponses:
            - statusCode: 200
              responseBody:
                description: OK
              responseModels:
                "application/json": GetOneEvaluationsModel

Suportado: summary, description, tags, pathParams, queryParams, headerParams, cookieParams, requestBody, requestModels, methodResponses (statusCode, responseBody.description, responseModels, responseHeaders).

Eventos httpApi e a forma abreviada (http: GET /path) também são lidos. Eventos http sem bloco documentation são ignorados, igual aos plugins antigos.

Extensões (opt-in)

Nada abaixo é ativado por padrão, exceto onde indicado.

| Campo em documentation | Default | O que faz | |---|---|---| | openapi | 3.0.3 | Versão a gerar. Em 3.1.x o schema é JSON Schema puro e a sanitização é desligada. | | servers / server | – | Server Objects do documento. | | description, contact, license, termsOfService | – | Campos de info. | | externalDocumentation | – | externalDocs do documento ou da operação. | | security.autoDetect | false | Eventos com authorizer recebem security e um scheme CognitoUserPool (apiKey no header Authorization) é declarado. | | security.schemes | – | Declara security schemes manualmente. | | corsHeaders | true | Injeta Access-Control-Allow-Origin nas respostas de eventos com cors (mantém a saída dos plugins antigos). false desliga. | | inferPathParams | true | Cria os parâmetros in: path presentes na URL mas ausentes da documentação — sem eles o spec é inválido. Cada inferência gera warning. | | includeUndocumented | false | Inclui eventos http sem bloco documentation. |

No nível da operação: operationId, deprecated, externalDocumentation, security, servers.

Diferenças em relação ao serverless-openapi-documenter

Compatível na entrada; a saída muda nestes pontos:

1. Schemas de parâmetro ficam inline. O plugin antigo promovia cada schema de parâmetro para components.schemas e referenciava por $ref — o que poluía components com pseudo-schemas (level, x-api-role) e gerava nomes com sufixo aleatório quando dois parâmetros homônimos divergiam (user_evaluation_id-b0e14f07-...). O resultado era válido, mas ilegível.
2. Path params ausentes são inferidos. Rota com {id} sem pathParams gerava spec inválido; agora o parâmetro é criado e um warning é emitido.
3. definitions/$defs são promovidos para components.schemas (prefixados com o nome do model) e os $ref internos reescritos.
4. Sanitização de JSON Schema para OAS 3.0: $schema, const, if/then/else, patternProperties etc. são removidos com warning; type: [x, "null"] vira type: x, nullable: true; examples: [...] vira example.
5. operationId duplicado é renomeado com sufixo em vez de gerar spec inválido.
6. Descrição padrão de resposta: statusCode sem responseBody.description recebe a reason phrase HTTP (201 → Created) em vez de ficar sem description (campo obrigatório).
7. Chaves de paths e components.schemas ordenadas alfabeticamente — diffs estáveis.

Validação

Roda por padrão; --no-validate desliga. Cobre o que quebra Swagger UI / Redoc / import no API Gateway:

• versão do OpenAPI, info.title, info.version
• {placeholder} da rota sem parâmetro in: path correspondente (e o inverso)
• required: true obrigatório em path param
• parâmetro (name, in) duplicado
• $ref de #/components/schemas/* que não resolve
• model referenciado em requestModels/responseModels sem declaração em documentation.models
• operationId duplicado
• resposta sem description; status code inválido
• security scheme não declarado
• tag usada e não declarada (warning)

Erros abortam a geração; warnings não (use --fail-on-warning). Para lint de estilo (servers ausente, info.license, operações sem security), rode redocly lint sobre a saída.

Desenvolvimento

npm install
npm test
npm run lint
npm run build
npm run typecheck

Publicação: npm run publish:patch / publish:minor / publish:major (roda lint + testes + build antes).

tests/fixtures/service/ espelha o layout real dos microsserviços (serverless.yml → serverless/custom.yml → serverless/docs/openapi/serverless.doc.yml → models/*.json) e é usado nos testes de ponta a ponta.