orator-api-description

A self-describing JSON API reference for Orator/Meadow servers. It serves the routes, request and response schemas, example payloads, and copy-pasteable curl snippets for an API, so an agent or a developer UI can learn the API instead of reverse-reading a web bundle. JSON, not YAML.

Most of it is auto-derived. Auto-CRUD routes generated by meadow-endpoints are described straight from the compiled Meadow model (the JsonSchema for request/response shapes, the DefaultObject for an example body, the presence of an IDCustomer column for tenant scoping). The live route table is the source of truth for what exists, so the description never drifts from what is actually mounted. Custom routes carry their method and path from that table plus a small annotation registry the host supplies for purpose, params and required entitlements (which cannot be read from code). A route with neither an entity match nor an annotation still appears, flagged Documented: false, so the inventory is always complete.

Routes

GET /<v>/API                     the inventory (filter with ?entity= ?method= ?kind= ?q= ?path=)
GET /<v>/API/Entities            entity index (name, primary key, tenant-scoped)
GET /<v>/API/Entities/:Entity    one entity's columns + request schema + example record
GET /<v>/API/Guides              guide index (key, title)
GET /<v>/API/Guides/:Key         one guide's markdown body

Use

const libApiDescription = require('orator-api-description');

libApiDescription.mount(pServiceServer, {
    Model: compiledMeadowModel,            // { Tables: { <Entity>: { MeadowSchema: { Schema, JsonSchema, DefaultObject, ... } } } }
    RouteProvider: () => liveRoutes,       // [ { method, path } ] -- e.g. off the router; falls back to introspection
    Annotations: annotationRegistry,       // { "GET /1.0/Account/Me": { Summary, Description, PathParams, QueryParams, Auth, ExampleRequestBody } }
    Guides: guides,                        // [ { Key, Title, Body } ]
    ExcludedEntities: { Account: true },   // entities with no auto-CRUD
    Version: '1.0',
    BaseURL: 'https://your-host',
    AuthGate: (pRequest) => isAuthenticated(pRequest)   // return truthy to allow; omit for public
});

The core (source/API-Description-Builder.js) is pure -- it takes plain data and returns plain objects, with no Orator, Fable or filesystem dependency -- so it is trivially testable and reusable. The mount adapter is a thin HTTP layer over it.

License

MIT