From c832d65faeef7e016afdde9aaa9bb1b7f901c81a Mon Sep 17 00:00:00 2001
From: Nathan Coad <nathan@thecoads.com>
Date: Wed, 7 Jan 2026 10:08:41 +1100
Subject: [PATCH] enhance readme

---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 43 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 30a006a..278aa23 100644
--- a/README.md
+++ b/README.md
@@ -8,8 +8,47 @@ This code references translation data provided by diagrams.net, previously draw.
 There is a version of this code hosted at https://g2d.coadcorp.com
 
 ## CLI
-`go build -o gliffy2drawio ./cmd/gliffy2drawio/main.go`
+Build the CLI:
+```bash
+go build -o gliffy2drawio ./cmd/gliffy2drawio
+```
 
-### Command line arguments
-- -in Input file path
-- -out Output file path
\ No newline at end of file
+### Command line usage
+```bash
+gliffy2drawio -in input.gliffy -out output.drawio
+```
+
+#### Flags
+- `-in`  (required) Path to the Gliffy JSON or .gliffy file.
+- `-out` (optional) Path to write the draw.io XML. If omitted, XML is written to stdout.
+
+## REST API
+The HTTP server exposes a simple REST endpoint plus docs.
+
+- Swagger UI: `http://localhost:8080/swagger`
+- OpenAPI spec: `http://localhost:8080/openapi.json`
+
+### Endpoint
+`POST /api/convert`
+
+**Request body**
+```json
+{
+  "data": "<gliffy JSON string>"
+}
+```
+
+**Response**
+```json
+{
+  "xml": "<draw.io XML string>",
+  "warning": "optional warning text"
+}
+```
+
+**Example**
+```bash
+curl -X POST http://localhost:8080/api/convert \
+  -H "Content-Type: application/json" \
+  -d '{"data": "'"$(cat sample-input.gliffy | tr -d "\n")"'" }'
+```