Apidocs (AI API Docs Portal): foundations

accepted

Status

accepted — 2026-05-09. Sector bootstrap (skeleton + 5 impl tickets) landed as part of /k-go services/ai audit wave (Modo C). Q1 resolved: domain docs.koder.dev (short, conventional, industry-standard); developers.koder.dev reserved for the future portal that combines docs + dashboards + API key management. Q2 resolved: own static-site generator built on a vetted FOSS base (Astro vs Hugo decision in impl ticket #002), not Mintlify (proprietary). Location decision: sector lives in services/ai/apidocs/ (owned by AI area, generated from AI service contracts); meta/sites/ remains for marketing/institutional surfaces.

Summary

Portal de docs API unificada pros services AI — análogo docs.anthropic.complatform.openai.comdocs.

Motivation

platform.koder.dev é catálogo de produtos, não docs API. Devs externos consumindo gatewayvoiceetc não têm onde ler. Bloqueia adoção pública.

Scope

In

  • Rendered OpenAPI specs por service
  • Code examples (curlpythondart/go)
  • Interactive try-it
  • Versioning

Out (yet)

  • Marketing (escopo landing-pages)
  • Tutorials longos (escopo separated docs)

Initial design

Surfaces

  • site estático gerado de OpenAPI (consumido por jet)
  • backend/ opcional — sem APIs próprias

Key APIs

  • consome /openapi.yaml de cada service
  • sem APIs próprias

Dependencies

  • cada service expõe /openapi.yaml
  • infra/net/jet — hospedagem
  • meta/sites/ — possível home

Relation to existing sectors

  • Cross-cutting — agrega specs de todos services AI
  • Possível morar em meta/sites/ (decisão da RFC)

Self-hosted-first analysis (5 gates)

  • G1 Feature parity: zero
  • G2 Performance: N/A
  • G3 Stability: N/A
  • G4 Capability: Mintlify-clone ou Swagger UI customizado
  • G5 Critical-path readiness: destrava adoção externa

Open questions

  • Q1: Domain — docs.koder.dev ou developers.koder.dev?
  • Q2: Generator — Mintlify FOSS, Redoc, ou próprio?

Next steps

  1. Ratificar esta RFC (1 round de comments).
  2. Criar sector dir services/ai/apidocs/ com koder.toml, README.md, skeleton.
  3. Abrir tickets de implementação em services/ai/apidocs/backlog/pending/.
  4. Registrar em meta/docs/stack/registries/self-hosted-pairs.md se substituir externo.