> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Neuro.Content.OpenApi

> OpenAPI 3.0.x document model and JSON content codec for Neuron packages

## Overview

`Neuro.Content.OpenApi` is the typed OpenAPI document model used by Neuron packages. It gives services a C# representation of an OpenAPI `3.0.x` document, factory methods for reading a parsed JSON dictionary, and `ToDictionary()` methods for serializing the model back to JSON.

It also includes `OpenApiJsonCodec`, a Waher content codec that lets Neuron services return an `OpenApiDocument` as normal `application/json`.

<Note>
  The repository and project URL are named `Neuron.Content.OpenApi`, while the NuGet package, assembly, and namespace are `Neuro.Content.OpenApi`.
</Note>

## Install the package

```bash theme={null}
dotnet add package Neuro.Content.OpenApi
```

or:

```xml theme={null}
<ItemGroup>
  <PackageReference Include="Neuro.Content.OpenApi" />
</ItemGroup>
```

The package targets `netstandard2.1` and depends on `Waher.IoTGateway` and `Waher.Runtime.Inventory`.

## What it owns

Use this package when you need to:

* Build an OpenAPI document in code
* Parse an existing OpenAPI JSON document into a typed model
* Mutate paths, operations, schemas, components, responses, or security definitions
* Return an OpenAPI document through Waher content handling
* Work with the document produced by `Neuro.Networking.HttpRouter.OpenApi`

It does not inspect controllers or generate routes by itself. That responsibility belongs to the HTTP router companion assembly, `Neuro.Networking.HttpRouter.OpenApi`.

## Relationship to the HTTP router

The HTTP router generator walks a `ControllerEndpointRouter` route tree and returns an `OpenApiDocument` from this package.

```csharp theme={null}
using Neuro.Content.OpenApi.Model;
using Neuro.Networking.HttpRouter.OpenApi;

OpenApiDocument Document = OpenApiGenerator.Generate(
    Router,
    new OpenApiInfo
    {
        Title = "Parklet API",
        Version = "3.0.0"
    });
```

After generation, you can add servers, components, security requirements, or other metadata using the `Neuro.Content.OpenApi.Model` types before returning the document.

```csharp theme={null}
Document.Servers.AddRange(OpenApiGenerator.CurrentServers());
await Response.Return(Document);
```

`Response.Return(Document)` can serialize the document because `OpenApiJsonCodec` implements Waher content encoding for `OpenApiDocument`.

## Document model

The root type is `OpenApiDocument`.

```csharp theme={null}
using Neuro.Content.OpenApi.Model;

OpenApiDocument Document = new OpenApiDocument
{
    Info = new OpenApiInfo
    {
        Title = "Parking API",
        Version = "1.0.0",
        Description = "HTTP API for parking areas and parking squares"
    }
};

Document.Servers.Add(new OpenApiServer
{
    Url = "https://api.example.com"
});
```

`OpenApiDocument.OpenApiVersion` defaults to `3.0.3`. The codec requires `Info` when encoding a document.

## Add paths and operations

Paths are represented by `OpenApiPathItem`. Each path item can hold HTTP method operations such as `Get`, `Post`, `Put`, `Patch`, and `Delete`.

```csharp theme={null}
OpenApiOperation ListParkingAreas = new OpenApiOperation
{
    Summary = "List parking areas",
    OperationId = "listParkingAreas"
};

ListParkingAreas.Tags.Add("Parking areas");
ListParkingAreas.Responses["200"] = new OpenApiResponse
{
    Description = "Success"
};

Document.AddPath(
    "/parking-areas",
    new OpenApiPathItem
    {
        Get = ListParkingAreas
    });
```

Use `Document.AddPath(...)` when adding paths manually. It validates that the path starts with `/`.

## Parse an OpenAPI document

`FromDictionary(...)` builds the typed model from a dictionary such as the object returned by `Waher.Content.JSON.Parse(...)`.

```csharp theme={null}
using System.Collections.Generic;
using Neuro.Content.OpenApi.Model;
using Waher.Content;

Dictionary<string, object> Data =
    (Dictionary<string, object>)JSON.Parse(Json);

OpenApiDocument Document = OpenApiDocument.FromDictionary(Data);

foreach (KeyValuePair<string, OpenApiPathItem> Path in Document.Paths)
{
    string Route = Path.Key;
    OpenApiPathItem Item = Path.Value;
}
```

The JSON root must contain an `openapi` field when decoded through `OpenApiJsonCodec`.

## Serialize a document

Every model type exposes `ToDictionary()` for JSON-compatible output.

```csharp theme={null}
using System.Collections.Generic;
using Neuro.Content.OpenApi.Model;
using Waher.Content;

Dictionary<string, object> Data = Document.ToDictionary();
string Json = JSON.Encode(Data, false);
```

When the Waher content pipeline is used, `OpenApiJsonCodec` performs this conversion for `OpenApiDocument` and emits `application/json`.

## Schema model

Schemas are polymorphic. `OpenApiSchema.FromDictionary(...)` chooses a concrete schema type based on `$ref`, `oneOf`, `allOf`, `type`, or object `properties`.

| OpenAPI shape                  | Model type             |
| ------------------------------ | ---------------------- |
| `$ref`                         | `OpenApiRefSchema`     |
| `type: string`                 | `OpenApiStringSchema`  |
| `type: integer`                | `OpenApiIntegerSchema` |
| `type: number`                 | `OpenApiNumberSchema`  |
| `type: boolean`                | `OpenApiBooleanSchema` |
| `type: array`                  | `OpenApiArraySchema`   |
| `type: object` or `properties` | `OpenApiObjectSchema`  |
| `oneOf`                        | `OpenApiOneOfSchema`   |
| `allOf`                        | `OpenApiAllOfSchema`   |

Reusable schemas live under `OpenApiComponents.Schemas`.

```csharp theme={null}
Document.Components = new OpenApiComponents();
Document.Components.Schemas["ParkingArea"] = new OpenApiObjectSchema
{
    Properties =
    {
        ["id"] = new OpenApiStringSchema { Format = "uuid" },
        ["name"] = new OpenApiStringSchema()
    },
    Required =
    {
        "id",
        "name"
    }
};
```

## Core types

| Area          | Types                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Root document | `OpenApiDocument`, `OpenApiInfo`, `OpenApiServer`                                                                      |
| Operations    | `OpenApiPathItem`, `OpenApiOperation`, `OpenApiParameter`, `OpenApiRequestBody`, `OpenApiResponse`, `OpenApiMediaType` |
| Components    | `OpenApiComponents`, `OpenApiSecurityScheme`, `OpenApiSecurityRequirement`                                             |
| Encoding      | `OpenApiJsonCodec`                                                                                                     |

## Codec behavior

`OpenApiJsonCodec` implements both `IContentEncoder` and `IContentDecoder` from `Waher.Content`.

* Encodes `OpenApiDocument` to `application/json`
* Decodes `application/json` into `OpenApiDocument` when the root object contains `openapi`
* Uses `OpenApiDocument.ToDictionary()` when writing JSON
* Uses `OpenApiDocument.FromDictionary(...)` when reading JSON
* Is discoverable through `Waher.Runtime.Inventory`

## Practical rules

* Set `Info.Title` and `Info.Version` before returning a document.
* Keep shared schemas, parameters, responses, and security schemes in `OpenApiComponents`.
* Prefer `OpenApiRefSchema` when reusing component schemas across multiple operations.
* Treat `FromDictionary(...)` and `ToDictionary()` as the boundary between JSON and typed C# code.
* Use `Neuro.Networking.HttpRouter.OpenApi` when you want controller routes to generate the document for you.

## What to read next

* [Neuron HTTP router](/neuron-development/first-party-packages/neuron-http-router)
* [HTTP router OpenAPI generation](/neuron-development/first-party-packages/neuron-http-router#openapi-document-generation)