// ── The OpenAPI fragment: the shared half ─────────────────────────────────
//
// The tags and component schemas your `#swagger.*` annotations refer to.
// `scripts/swaggerFragment.js` feeds this to swagger-autogen; the per-endpoint
// detail lives beside each route, exactly as it does in core.
//
// **Two rules about names, and both belong to the MERGED document rather than to
// this file** (MODULE_API.md §6.1a). Core merges every started module's fragment
// over its own spec and serves the result at `/api/docs.json`, and core wins any
// key collision:
//
//   • **Namespace what you DEFINE.** `ExamplegameWorldStatus`, not `WorldStatus`.
//     A second game's module describing the same idea under the same bare name
//     would silently clobber yours or be clobbered by it. The prefix is what
//     makes two modules able to coexist.
//   • **Reference what CORE defines by core's name.** `#/components/schemas/Error`
//     and `ValidationError` are core's; point at them and do not redefine them.
//     They resolve in the merged document, where core's definitions are. Shipping
//     your own copy is a collision core drops — which is the right outcome, and
//     an expensive way to learn it.
//
// A tag is how the docs UI groups operations. Name yours after your module so an
// operator reading `/api/docs` can see which operations arrived with it.
//
// **swagger-autogen renders `components.schemas` from an EXAMPLE object, not from
// raw OpenAPI.** `{ type: 'object' }` comes back as a meta-description of itself.
// That is uniform across core's committed spec and is the house shape — match it,
// do not fight it.

module.exports = {
  tags: [
    {
      name: 'Public · Example Game',
      description: 'Live world data, as last reported by the game server',
    },
  ],
  components: {
    schemas: {
      ExamplegameWorldStatus: {
        type: 'object',
        description: 'The game world’s status (GET /public/world/status).',
        properties: {
          online: { type: 'boolean', example: true },
          players: { type: 'integer', example: 12 },
          worldName: { type: 'string', nullable: true, example: 'Example World' },
          updatedAt: { type: 'string', format: 'date-time', nullable: true },
          stale: {
            type: 'boolean',
            description: 'Has nothing reported in longer than the freshness window? A stale row is reported offline.',
            example: false,
          },
        },
      },
    },
  },
}