magmalake flare_mlake

flare_mlake · API · openapi

flare.openapi.spec

OpenAPI 3.1 spec data model + JSON serializer.

The model mirrors the OpenAPI 3.1 schema at the surface flare's comptime spec generator can populate from a router. We don't attempt a full schema reflector here -- only the structural elements a handler chain can produce mechanically:

  • info (title + version)
  • paths: per-URI list of operations
  • per-operation: summary, parameters, requestBody, responses

The emitter writes a deterministic JSON document with alphabetically-sorted object keys so two builds of the same router produce byte-identical output (useful for caching the Swagger UI bundle, diffing spec changes in PRs, etc.).

References:

Structs

OpenApiInfo

struct OpenApiInfo

Top-level info object.

Implements Copyable, Movable

Fields
title: String
version: String
description: String

OpenApiParameter

struct OpenApiParameter

A single parameter (path / query / header).

Implements Copyable, Movable

Fields
name: String
location: String
required: Bool
schema_type: String

OpenApiResponse

struct OpenApiResponse

A single response variant.

Implements Copyable, Movable

Fields
status: String
description: String
content_type: String

OpenApiOperation

struct OpenApiOperation

A single <method> <path> operation.

Implements Copyable, Movable

Fields
method: String
summary: String
operation_id: String
parameters: List[OpenApiParameter]
responses: List[OpenApiResponse]

OpenApiPath

struct OpenApiPath

All operations registered under one URI template.

Implements Copyable, Movable

Fields
template: String
operations: List[OpenApiOperation]

OpenApiSpec

struct OpenApiSpec

Root OpenAPI 3.1 document.

Implements Copyable, Movable

Fields
info: OpenApiInfo
paths: List[OpenApiPath]

new

def new(title: String, version: String) -> Self

Functions

emit_openapi_json

def emit_openapi_json(spec: OpenApiSpec) -> String

Serialise an OpenAPI spec to JSON.

The output is deterministic: object keys appear in a fixed order (alphabetical at every depth where the spec doesn't impose its own ordering), so two builds of the same router produce byte-identical documents.