Initial version
This commit is contained in:
@@ -1,3 +1,162 @@
|
||||
# EonaCat.DoxaApi
|
||||
|
||||
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!
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user