178 lines
6.8 KiB
Markdown
178 lines
6.8 KiB
Markdown
# EonaCat.DoxaApi
|
|
|
|
**A modern, self-contained API documentation UI for ASP.NET Core with built-in analytics and monitoring**
|
|
|
|
DoxaApi reflects over your controllers, generates an OpenAPI-compatible document, and serves a fast, single-page documentation UI.
|
|
|
|
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
dotnet add package EonaCat.DoxaApi
|
|
```
|
|
|
|
```csharp
|
|
using EonaCat.DoxaApi;
|
|
using EonaCat.DoxaApi.Middleware;
|
|
|
|
var builder = WebApplication.CreateBuilder(args);
|
|
|
|
builder.Services.AddControllers();
|
|
builder.Services.AddDoxaApi(options =>
|
|
{
|
|
options.Title = "Sample API";
|
|
options.Description = "A demo service showing off the DoxaApi UI.";
|
|
options.Version = "v1";
|
|
options.AccentColor = "#6366f1";
|
|
|
|
// Optional: declare how clients authenticate.
|
|
options.AddBearerAuth(description: "Sign in and paste your JWT here.");
|
|
});
|
|
|
|
var app = builder.Build();
|
|
|
|
app.UseRouting();
|
|
app.UseDoxaApi(options => options.RoutePrefix = "doxa");
|
|
app.MapControllers();
|
|
|
|
app.Run();
|
|
```
|
|
|
|
Run the app and open `/doxa`. That's the whole setup.
|
|
|
|
DoxaApi reads standard `///` XML doc comments and a handful of optional attributes:
|
|
|
|
```csharp
|
|
[ApiController]
|
|
[Route("api/users")]
|
|
[DoxaApiGroup("Users")]
|
|
public class UsersController : ControllerBase
|
|
{
|
|
/// <summary>Creates a new user.</summary>
|
|
/// <param name="request">The user to create.</param>
|
|
/// <returns>The created user.</returns>
|
|
[HttpPost]
|
|
[DoxaApiExample("""{ "name": "Grace Hopper", "email": "grace@example.com" }""")]
|
|
public ActionResult<User> Create([FromBody] CreateUserRequest request) { ... }
|
|
|
|
[HttpDelete("{id}")]
|
|
[Obsolete("Use POST /api/users/{id}/archive instead.")]
|
|
public IActionResult Delete(Guid id) { ... }
|
|
}
|
|
```
|
|
|
|
| Attribute | Purpose |
|
|
|||
|
|
| `[DoxaApiGroup("Name")]` | Groups endpoints in the nav (class or method level) |
|
|
| `[DoxaApiSummary("...")]` | Overrides the auto-generated summary |
|
|
| `[DoxaApiDescription("...")]` | Adds a longer description |
|
|
| `[DoxaApiExample("""{ ... }""")]` | Supplies a realistic request body example |
|
|
| `[DoxaApiHidden]` | Excludes a controller/action from the docs entirely |
|
|
| `[DoxaApiAuth("schemeId")]` | Marks an endpoint as requiring a specific security scheme |
|
|
| `[DoxaApiAllowAnonymous]` | Marks an endpoint as public, overriding any default scheme |
|
|
| `[Obsolete("...")]` | Flags the endpoint as deprecated in the UI |
|
|
|
|
Standard ASP.NET Core `[Authorize]` / `[AllowAnonymous]` attributes are also detected automatically.
|
|
|
|
|
|
|
|
## Authentication
|
|
|
|
Declare the security schemes your API actually uses, and DoxaApi takes care of the rest - detecting which endpoints need them, badging them in the docs, and prompting for credentials in the UI's **Authorize** dialog.
|
|
|
|
```csharp
|
|
builder.Services.AddDoxaApi(options =>
|
|
{
|
|
options.AddBearerAuth(); // Authorization: Bearer <token>
|
|
options.AddApiKeyAuth("apiKey", "X-API-Key", "header"); // custom header
|
|
options.AddBasicAuth(); // HTTP Basic
|
|
options.AddOAuth2ClientCredentials("oauth2",
|
|
tokenUrl: "https://auth.example.com/connect/token",
|
|
scopes: new() { ["api.read"] = "Read access" });
|
|
|
|
options.DefaultSecurityScheme = "bearer"; // applied to any [Authorize] endpoint
|
|
// without an explicit [DoxaApiAuth]
|
|
});
|
|
```
|
|
|
|
Credentials entered in the UI are stored in the browser's `localStorage` (never sent anywhere except the documented API itself) and are automatically attached to every "Try it" request, cURL snippet, and generated code sample for endpoints that require them.
|
|
|
|
|
|
|
|
## Analytics Dashboard
|
|
|
|
The built-in **Analytics Dashboard** provides real-time insights into your API usage:
|
|
|
|
- **Endpoint Statistics** - View total requests, success rate, and average response times per endpoint
|
|
- **Request History** - Track recent requests with status codes and response times
|
|
- **Performance Metrics** - Monitor overall API health and uptime
|
|
- **Top Endpoints** - Identify your most-used endpoints at a glance
|
|
|
|
Click the **Dashboard** button in the top navigation to view live analytics. Metrics are automatically collected and refreshed every 5 seconds.
|
|
|
|
```csharp
|
|
// Access analytics programmatically
|
|
var metricsCollector = app.ApplicationServices.GetService<MetricsCollector>();
|
|
if (metricsCollector != null)
|
|
{
|
|
var dashboard = metricsCollector.GetDashboard();
|
|
var recentRequests = metricsCollector.GetRecentRequests(limit: 50);
|
|
}
|
|
```
|
|
|
|
Get the analytics JSON via:
|
|
```
|
|
GET /doxa/analytics
|
|
```
|
|
|
|
All API requests and responses are automatically serialized, ensuring consistent behavior across your entire API documentation.
|
|
|
|
## Authoring your documentation
|
|
|
|
Every endpoint can return a schema-shaped fake response without touching your real controllers - flip the **"Send to mock server"** toggle in the Try-it panel, or call it directly:
|
|
|
|
```
|
|
GET /doxa/mock?operationId=Users_GetById
|
|
```
|
|
|
|
Useful for frontend teams who need to start building against an API before the backend is finished. Disable it with `options.EnableMockServer = false;` if you'd rather it not be exposed.
|
|
|
|
## API console
|
|
|
|
The **Console** (top bar) lets you fire an arbitrary HTTP request - any method, any absolute URL, custom headers and body - through the server rather than the browser. Because the request happens server-side, it isn't subject to the browser's CORS policy, which makes it useful for poking at a different host than the one serving the docs. Disable with `options.EnableConsole = false;`.
|
|
|
|
## Code generation
|
|
|
|
Every endpoint's Try-it panel includes a **Code** tab with ready-to-paste snippets in cURL, JavaScript (`fetch`), Python (`requests`), C# (`HttpClient`), and Go (`net/http`) - automatically including whatever auth headers you've configured.
|
|
|
|
## Comparing spec versions
|
|
|
|
Click **Compare** and upload a previous (or upcoming) OpenAPI/Swagger/DoxaApi JSON file to see exactly which endpoints were added, removed, or changed - including parameter, request-body, and security differences. Handy in code review for catching accidental breaking changes before they ship.
|
|
|
|
## Import & export
|
|
|
|
DoxaApi documents are available at:
|
|
|
|
- `/doxa/doxaApi.json` - native format
|
|
- `/doxa/openapi.json` - OpenAPI 3.0.3
|
|
- `/doxa/swagger.json` - Swagger 2.0
|
|
|
|
...and the **Import** button accepts any of the three formats back in, so you can merge in a hand-written spec, or load an API documented elsewhere.
|
|
|
|
## Configuration reference
|
|
|
|
```csharp
|
|
builder.Services.AddDoxaApi(options =>
|
|
{
|
|
options.Title = "My API";
|
|
options.Description = "...";
|
|
options.Version = "v1";
|
|
options.RoutePrefix = "doxa"; // served at /doxa
|
|
options.Servers.Add("https://api.example.com");
|
|
options.Theme = "auto"; // "auto" | "dark" | "light"
|
|
options.AccentColor = "#6366f1";
|
|
options.EnableMockServer = true;
|
|
options.EnableConsole = true;
|
|
});
|
|
``` |