Neuro.Content.OpenApi - Neuron Agent API

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.

The repository and project URL are named Neuron.Content.OpenApi, while the NuGet package, assembly, and namespace are Neuro.Content.OpenApi.

Install the package

dotnet add package Neuro.Content.OpenApi

or:

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

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.

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.

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.

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(...).

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.

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.

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.

​Overview

​Install the package

​What it owns

​Relationship to the HTTP router

​Document model

​Add paths and operations

​Parse an OpenAPI document

​Serialize a document

​Schema model

​Core types

​Codec behavior

​Practical rules

​What to read next

Overview

Install the package

What it owns

Relationship to the HTTP router

Document model

Add paths and operations

Parse an OpenAPI document

Serialize a document

Schema model

Core types

Codec behavior

Practical rules

What to read next