# flare.openapi.spec

> A module of flare_mlake's API.

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:
- https://spec.openapis.org/oas/v3.1.0
- JSON Schema 2020-12: https://json-schema.org/specification.html

## Structs

### `OpenApiInfo`

```mojo
struct OpenApiInfo
```

Top-level ``info`` object.

Implements: `Copyable`, `Movable`

Fields:

- `title: String`
- `version: String`
- `description: String`

### `OpenApiParameter`

```mojo
struct OpenApiParameter
```

A single parameter (path / query / header).

Implements: `Copyable`, `Movable`

Fields:

- `name: String`
- `location: String`
- `required: Bool`
- `schema_type: String`

### `OpenApiResponse`

```mojo
struct OpenApiResponse
```

A single response variant.

Implements: `Copyable`, `Movable`

Fields:

- `status: String`
- `description: String`
- `content_type: String`

### `OpenApiOperation`

```mojo
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`

```mojo
struct OpenApiPath
```

All operations registered under one URI template.

Implements: `Copyable`, `Movable`

Fields:

- `template: String`
- `operations: List[OpenApiOperation]`

### `OpenApiSpec`

```mojo
struct OpenApiSpec
```

Root OpenAPI 3.1 document.

Implements: `Copyable`, `Movable`

Fields:

- `info: OpenApiInfo`
- `paths: List[OpenApiPath]`

#### `new`

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

## Functions

### `emit_openapi_json`

```mojo
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.