EonaCat.DoxaApi/README.md

# EonaCat.DoxaApi

A self-contained, API documentation UI for ASP.NET Core

EonaCat.DoxaApi scans your controllers with plain `System.Reflection` and ASP.NET Core's own `IActionDescriptorCollectionProvider`, 
builds a small OpenAPI-like JSON document with `System.Text.Json`, and serves a UI
This can also be used in an offline environment!

![alt text](image.png)

## Install

```bash
dotnet add package EonaCat.DoxaApi
```

## Quick start

```csharp
using EonaCat.DoxaApi;
using EonaCat.DoxaApi.Middleware;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddEonaCat.DoxaApi(options =>
{
    options.Title = "My API";
    options.Description = "Internal service API";
    options.AccentColor = "#6366f1"; // any hex color
});

var app = builder.Build();
app.UseRouting();
app.UseEonaCat.DoxaApi(); // serves UI at /doxa and spec at /doxa/DoxaApi.json
app.MapControllers();

app.Run();
```

Run your app and open `https://localhost:xxxx/doxa`.

## Features

- **Route-table style navigation** - endpoints grouped by controller, each method color-coded (GET/POST/PUT/PATCH/DELETE), searchable with `/`.
- **Schema viewer** - nested request/response shapes rendered as readable, syntax-colored trees, with required fields marked.
- **Try it out** - a real three-pane layout: browse → inspect → call, with path/query/header inputs, an editable JSON body (pre-filled with a generated example), and a live response panel with status, timing, and syntax-highlighted JSON.
- **Light & dark themes**, persisted, with a system-preference default.
- **XML doc comment support** - `/// <summary>`, `<param>`, and `<returns>` are read directly from your project's generated `.xml` doc file (enable `<GenerateDocumentationFile>true</GenerateDocumentationFile>` in your csproj).
- **Attributes for fine control**: `[EonaCat.DoxaApiGroup]`, `[EonaCat.DoxaApiSummary]`, `[EonaCat.DoxaApiDescription]`, `[EonaCat.DoxaApiExample]`, `[EonaCat.DoxaApiHidden]`.
- **Zero external NuGet dependencies** - only references your app's own ASP.NET Core shared framework.

## Configuration reference

```csharp
builder.Services.AddEonaCat.DoxaApi(options =>
{
    options.Title = "My API";          // shown in the top bar and browser tab
    options.Description = "...";       // shown on the welcome screen
    options.Version = "v1";
    options.RoutePrefix = "doxa";  // UI served at /{RoutePrefix}
    options.AccentColor = "#6366f1";   // primary button/accent color
    options.Theme = "auto";            // "auto" | "light" | "dark"
});
```

## Attributes

```csharp
[EonaCat.DoxaApiGroup("Users")]               // override the left-nav group name
public class UsersController : ControllerBase
{
    /// <summary>Lists all users.</summary>     // picked up automatically
    [HttpGet]
    public ActionResult<List<User>> GetUsers() => ...;

    [HttpPost]
    [EonaCat.DoxaApiExample("""{ "name": "Ada" }""")]    // overrides the auto-generated example
    public ActionResult<User> Create(CreateUserRequest request) => ...;

    [HttpDelete("{id}")]
    [EonaCat.DoxaApiHidden]                              // omit from docs entirely
    public IActionResult Delete(Guid id) => ...;
}
```

## OpenAPI & Swagger

EonaCat.DoxaApi exposes dedicated endpoints for importing and exporting industry-standard spec formats alongside its own native JSON.

### Export

| URL | Format | Notes |
|-----|--------|-------|
| `/{RoutePrefix}/DoxaApi.json` | Native EonaCat.DoxaApi JSON | Always available; used by the built-in UI |
| `/{RoutePrefix}/openapi.json` | **OpenAPI 3.0.3** | Import into Postman, Insomnia, Stoplight, etc. |
| `/{RoutePrefix}/swagger.json` | **Swagger 2.0** | Import into older tools, AWS API Gateway, Azure APIM, etc. |

```bash
# Download the OpenAPI 3.0 spec
curl http://localhost:5000/doxa/openapi.json -o openapi.json

# Download the Swagger 2.0 spec
curl http://localhost:5000/doxa/swagger.json -o swagger.json
```

### Import

`POST /{RoutePrefix}/import`

Send any OpenAPI 3.x or Swagger 2.0 JSON document in the request body. The server detects the format automatically and returns the native EonaCat.DoxaApi document.

```bash
# Import a third-party OpenAPI spec and get the EonaCat.DoxaApi document back
curl -X POST http://localhost:5000/doxa/import \
     -H "Content-Type: application/json" \
     --data-binary @path/to/openapi.json
```

**Use cases:**
- Preview any public or third-party OpenAPI/Swagger spec in the EonaCat.DoxaApi UI
- Validate that your spec round-trips correctly through import → export
- Use the import endpoint as a conversion proxy (OpenAPI 3 ↔ Swagger 2)

### Programmatic use

The `OpenApiExporter`, `SwaggerExporter`, and `OpenApiImporter` classes in the
`EonaCat.DoxaApi.Interop` namespace are `public static` and can be used directly in your
own code:

```csharp
using EonaCat.DoxaApi.Interop;
using EonaCat.DoxaApi.Models;

// Export: ApiDocument → OpenAPI 3.0 JsonObject
ApiDocument doc = /* ... */;
System.Text.Json.Nodes.JsonObject openApi = OpenApiExporter.Export(doc);
string json = openApi.ToJsonString(new JsonSerializerOptions { WriteIndented = true });

// Export: ApiDocument → Swagger 2.0 JsonObject
System.Text.Json.Nodes.JsonObject swagger = SwaggerExporter.Export(doc);

// Import: OpenAPI 3.x or Swagger 2.0 string → ApiDocument
ApiDocument imported = OpenApiImporter.Import(File.ReadAllText("openapi.json"));

// Import from a Stream
await using var stream = File.OpenRead("swagger.json");
ApiDocument imported2 = OpenApiImporter.Import(stream);
```

## Sample project

See `/sample/SampleApi` for a complete working example with two controllers (`Users`, `Orders`) demonstrating nested objects, enums, arrays, path/query parameters, and a deprecated endpoint.

```bash
cd sample/SampleApi
dotnet run
# open http://localhost:5000/doxa
```

## License

MIT