Files

Mahmoud-Emad 3669edf24e feat: implement built-in API documentation system

- Introduce `DocRegistry` for managing API documentation
- Add automatic discovery of markdown documentation from templates
- Implement a new web-based documentation viewer at `/docs`
- Include basic markdown to HTML conversion logic
- Register core HeroServer API documentation and an example 'comments' API

2025-09-16 12:54:16 +03:00

1.8 KiB

Raw Blame History

HeroServer Documentation System

The HeroServer features a built-in documentation system that automatically discovers and serves API documentation with a clean web interface.

Adding New Documentation

Create a markdown file in lib/hero/heroserver/templates/pages/:
```
# Example: lib/hero/heroserver/templates/pages/calendar.md
```

Write your documentation using standard markdown:

# Calendar API

A comprehensive calendar management service.

## Endpoints

### Create Calendar

**Endpoint:** `POST /calendars`

**Request:**
```json
{
  "name": "My Calendar"
}

Response:

{
  "id": "cal_123",
  "name": "My Calendar"
}

Restart the server - Documentation available at http://localhost:8080/docs/calendar

Features

Auto-Discovery: Scans templates/pages/ for .md files on startup
Built-in Viewer: Professional web interface with sidebar navigation
Dynamic Rendering: Markdown converted to HTML on-demand
Zero Configuration: Just add markdown files and they appear automatically

Documentation Structure

Your markdown files should follow this structure:

# API Name

Brief description of your API.

## Overview

Detailed overview...

## Endpoints

### Create Resource

**Endpoint:** `POST /resources`

**Request:**
```json
{
  "name": "example"
}

Response:

{
  "id": "123",
  "name": "example"
}

Error Handling

Standard HTTP status codes and error responses...

Accessing Documentation

Main Index: http://localhost:8080/docs (redirects to first available API)
Specific API: http://localhost:8080/docs/{api_name}
Example: http://localhost:8080/docs/calendar

1.8 KiB Raw Blame History