tlecommunity.com / api-spec
OpenAPI 3.0 compliant spec for TLE Community.
Star
Fork 1
Watch
api-spec CLAUDE.md
3.5 kB
Markdown
at main

CLAUDE.md #

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is #

A hand-authored OpenAPI 3.1.0 specification for The Lacuna Expanse game API, written in TypeScript and assembled into a plain JS spec object that's rendered in-browser with Swagger UI. This repo is not a server or client implementation — it only defines and previews the API contract.

The spec describes a new /v2 layout of an existing API (not the original), and per src/spec.ts's info.description is intended only for use with the "TLE Community" codebase.

Commands #

  • npm start — runs vite, launching a dev server on port 3000 that renders the current spec via Swagger UI for visual inspection. This is the only script defined and the primary way to check your work.

There is no lint, test, build, or spec-validation tooling in this repo (no tsconfig.json, no ESLint config, no CI). Prettier is configured (.prettierrc.json) and applied via VS Code's format-on-save (.vscode/settings.json); there's no format script, so run npx prettier --write . if formatting from the CLI.

Architecture #

Boot path: index.html → index.ts calls SwaggerUI({ dom_id: '#main', spec }) using the assembled spec object from src/spec.ts.

Spec assembly (src/spec.ts): builds the top-level OpenAPI document — { openapi, info, servers, paths, components } — importing paths from src/spec/paths.ts and components from src/spec/components.ts.

Paths are composed per resource, then merged:

  • src/spec/paths.ts — export const paths = { ...empire, ...body }. To add a new resource group, create a file under src/spec/paths/ exporting a named object keyed by full path strings, then spread it in here.
  • src/spec/paths/empire.ts and src/spec/paths/body.ts define the actual endpoints. All are post, JSON-RPC style (matching the underlying game API).

Reuse helpers (src/spec/chunks.ts) — every path definition composes these rather than writing raw OpenAPI objects:

  • security() — adds the token-auth requirement
  • requestBodySchema(schema) — builds a requestBody
  • response200(description, resultSchema) — standard {id, jsonrpc, result} 200 response
  • response500() — standard RPC error response ($refs components.schemas.rpc_error)
  • statusSchema() — the common {server, empire, body} status object

Per the file's own comment, these helpers intentionally go beyond strict OpenAPI-authoring convention to keep the TypeScript source DRY — the final emitted spec is still plain OpenAPI JSON.

Shared schemas (src/spec/components.ts): securitySchemes.tokenHttpAuthentication (custom Authorization: Token <session_id> header) and schemas.{body_status, empire_status, rpc_error, server_status}. rpc_error enumerates the game's JSON-RPC error codes (1000–1200) with their meanings as inline comments. Reuse these via $ref: '#/components/schemas/...' instead of redefining shapes inline in a path.

src/auto-captured-data.ts (~14k lines) is temporary reference material captured via OpenAPI Dev Tools from live traffic against the original (non-/v2) API. It is not imported anywhere and not part of the emitted spec — treat it purely as source material to consult when hand-authoring new endpoints under src/spec/paths/, not as output to edit or keep in sync.