The client API described in OpenAPI, and both APIs in Swagger UI
CI / test (push) Failing after 6m12s

/v1/openapi.json is the API clients use — OpenAI's endpoints, Anthropic's,
and what llmgw adds — in OpenAPI 3.1, generated from internal/clientapi's
route table by the generator the admin API's document comes from, now
told each document's title, server, token and error. A test reads the
router's mux.HandleFunc calls and refuses a route described and not
mounted, or mounted and not described. Asked for before there is a key,
so it needs none.

/docs/api shows it in Swagger UI 5.33.1 (Apache 2.0, served from the
gateway as the page's policy requires): Authorize takes a key, Try it out
sends to this gateway. Staff are offered the admin API's document too,
from /docs/api/admin.json, which nobody else is given.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5.5 committed 2026-10-10 20:22:48 +02:00
1 parent 41601bc5ef
commit fd3c7bda32
26 files changed
+3956 -48

No files matched your search

+119 -44
View File
@@ -28,6 +28,7 @@ import (
"time"
"unicode"
"gitea.mynodes.xyz/ilker/llmgw/internal/clientapi"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
)
@@ -35,10 +36,68 @@ import (
// from any other is described without comments.
const Module = "gitea.mynodes.xyz/ilker/llmgw"
// Generate renders the document for routes, reading doc comments from the
// Doc is what one document says of itself and its API: the two APIs llmgw
// has, the admin listener's and the client's, are described by one
// generator from their route tables.
type Doc struct {
Title, Description string
// ServerURL and ServerDescription are where it is served by default.
ServerURL, ServerDescription string
// Scheme is the bearer token's name in the document, SchemeDescription
// what it is.
Scheme, SchemeDescription string
// Error is a value of the type every refusal answers with.
Error any
// Prefix is taken off paths to name operations and tags.
Prefix string
// Home is the package whose types are named alone; others are named
// with their package.
Home string
// Actor is whether changes take the admin API's X-Llmgw-Actor header.
Actor bool
}
// Admin is the admin API's document.
var Admin = Doc{
Title: "llmgw admin API", Description: infoDescription,
ServerURL: "http://127.0.0.1:9090", ServerDescription: "The admin listener at its default address, admin_listen.",
Scheme: "adminToken",
SchemeDescription: "The admin token: the contents of /var/lib/llmgw/admin-token on the " +
"control plane (admin_token_file), readable by root and the server. " +
"Sent as Authorization: Bearer TOKEN.",
Error: adminapi.ErrorView{}, Prefix: "/api/v1/", Home: reflect.TypeOf(adminapi.Route{}).PkgPath(), Actor: true,
}
// Client is the client API's document: the API on :8080 clients use.
var Client = Doc{
Title: "llmgw client API", Description: clientDescription,
ServerURL: "http://localhost:8080", ServerDescription: "A gateway at its default address, listen.",
Scheme: "apiKey",
SchemeDescription: "An API key, sk-llmgw-…, made with `llmgw keys create` or on the portal's profile page. " +
"Sent as Authorization: Bearer KEY; /v1/messages also takes it as x-api-key.",
Error: clientapi.Error{}, Prefix: "/v1/", Home: reflect.TypeOf(clientapi.Error{}).PkgPath(),
}
const clientDescription = "OpenAI's API, as llmgw serves it, and what llmgw adds: pictures and 3D models from " +
"ComfyUI, knowledge bases, memory notes, stored conversations.\n\n" +
"The SDKs of OpenAI and Anthropic work against it unchanged: set the base URL to the gateway's /v1 and the " +
"key to an llmgw key. A request carries more than is listed here: what the gateway does not read goes to " +
"the engine as it came. Headers llmgw reads: x-llmgw-thread (continue a stored conversation), " +
"x-llmgw-knowledge (answer from these collections), x-llmgw-tags (tags kept with the usage), " +
"x-session-id (stay on one replica). Headers it sends back: x-request-id, x-llmgw-served-model, " +
"x-llmgw-hardware, x-llmgw-seed, and Retry-After when waiting helps.\n\n" +
"Generated from the route table in internal/clientapi; see docs/clients.md."
// Generate renders the admin API's document, reading doc comments from the
// repository at root.
func Generate(root string, routes []adminapi.Route, pathParams map[string]string) ([]byte, error) {
g := &generator{root: root, docs: map[string]map[string]typeDoc{}, names: map[reflect.Type]string{}}
return GenerateDoc(root, Admin, routes, pathParams)
}
// GenerateDoc renders one API's document.
func GenerateDoc(root string, d Doc, routes []adminapi.Route, pathParams map[string]string) ([]byte, error) {
errorType := reflect.TypeOf(d.Error)
g := &generator{root: root, docs: map[string]map[string]typeDoc{}, names: map[reflect.Type]string{}, d: d}
// Every named struct reachable from a body first, so a name two
// packages share can be told apart before either is written: by the name
@@ -68,7 +127,7 @@ func Generate(root string, routes []adminapi.Route, pathParams map[string]string
if err != nil {
return nil, err
}
tags[tagOf(r.Path)] = true
tags[g.tagOf(r.Path)] = true
item.set(strings.ToLower(r.Method), op)
}
slices.Sort(order)
@@ -92,42 +151,42 @@ func Generate(root string, routes []adminapi.Route, pathParams map[string]string
tagList = append(tagList, obj("name", t))
}
components := obj(
"securitySchemes", obj(d.Scheme, obj(
"type", "http",
"scheme", "bearer",
"description", d.SchemeDescription,
)),
)
if d.Actor {
components.set("parameters", obj("Actor", obj(
"name", "X-Llmgw-Actor",
"in", "header",
"required", false,
"description", "Who the change is recorded as made by in the audit log: letters, digits "+
"and ._-@, at most 64. unknown when absent.",
"schema", obj("type", "string"),
)))
}
components.set("responses", obj(
"Error", obj("description", "Refused: the error says why.",
"content", obj("application/json", obj("schema", errorSchema))),
"Unauthorized", obj("description", "The token is missing or wrong.",
"content", obj("application/json", obj("schema", errorSchema))),
))
components.set("schemas", schemas)
doc := obj(
"openapi", "3.1.0",
"info", obj(
"title", "llmgw admin API",
"title", d.Title,
"version", "v1",
"description", infoDescription,
"description", d.Description,
),
"servers", []any{obj("url", "http://127.0.0.1:9090",
"description", "The admin listener at its default address, admin_listen.")},
"security", []any{obj("adminToken", []any{})},
"servers", []any{obj("url", d.ServerURL, "description", d.ServerDescription)},
"security", []any{obj(d.Scheme, []any{})},
"tags", tagList,
"paths", pathsObj,
"components", obj(
"securitySchemes", obj("adminToken", obj(
"type", "http",
"scheme", "bearer",
"description", "The admin token: the contents of /var/lib/llmgw/admin-token on the "+
"control plane (admin_token_file), readable by root and the server. "+
"Sent as Authorization: Bearer TOKEN.",
)),
"parameters", obj("Actor", obj(
"name", "X-Llmgw-Actor",
"in", "header",
"required", false,
"description", "Who the change is recorded as made by in the audit log: letters, digits "+
"and ._-@, at most 64. unknown when absent.",
"schema", obj("type", "string"),
)),
"responses", obj(
"Error", obj("description", "Refused: the error says why.",
"content", obj("application/json", obj("schema", errorSchema))),
"Unauthorized", obj("description", "The admin token is missing or wrong.",
"content", obj("application/json", obj("schema", errorSchema))),
),
"schemas", schemas,
),
"components", components,
)
b, err := marshal(doc)
if err != nil {
@@ -154,12 +213,12 @@ const infoDescription = "The control plane's management API: what `llmgw ctl` an
// operation builds one route's operation object.
func (g *generator) operation(r adminapi.Route, pathParams map[string]string) (object, error) {
var op object
op.set("operationId", operationID(r.Method, r.Path))
op.set("operationId", g.operationID(r.Method, r.Path))
op.set("summary", r.Summary)
if r.Description != "" {
op.set("description", r.Description)
}
op.set("tags", []any{tagOf(r.Path)})
op.set("tags", []any{g.tagOf(r.Path)})
var params []any
segs := strings.Split(strings.Trim(r.Path, "/"), "/")
@@ -174,7 +233,7 @@ func (g *generator) operation(r adminapi.Route, pathParams map[string]string) (o
}
desc, ok := pathParams[key]
if !ok {
return nil, fmt.Errorf("%s %s: no description of %s in adminapi.PathParams", r.Method, r.Path, key)
return nil, fmt.Errorf("%s %s: no description of %s in the path parameters", r.Method, r.Path, key)
}
params = append(params, obj("name", name, "in", "path", "required", true,
"description", desc, "schema", obj("type", "string")))
@@ -192,7 +251,7 @@ func (g *generator) operation(r adminapi.Route, pathParams map[string]string) (o
p.set("schema", obj("type", t))
params = append(params, p)
}
if r.Method != "GET" && r.Method != "HEAD" {
if g.d.Actor && r.Method != "GET" && r.Method != "HEAD" {
params = append(params, obj("$ref", "#/components/parameters/Actor"))
}
if len(params) > 0 {
@@ -200,8 +259,12 @@ func (g *generator) operation(r adminapi.Route, pathParams map[string]string) (o
}
if r.Request != nil {
ct := "application/json"
if r.Form {
ct = "multipart/form-data"
}
body := obj("required", !r.OptionalBody,
"content", obj("application/json", obj("schema", g.schema(reflect.TypeOf(r.Request)))))
"content", obj(ct, obj("schema", g.schema(reflect.TypeOf(r.Request)))))
op.set("requestBody", body)
}
@@ -209,10 +272,22 @@ func (g *generator) operation(r adminapi.Route, pathParams map[string]string) (o
if status == 0 {
status = 200
}
content := obj("application/json", obj("schema", g.schema(reflect.TypeOf(r.Response))))
var content object
switch {
case r.Binary != "":
content = obj(r.Binary, obj("schema", obj("type", "string", "format", "binary")))
case r.Response == nil:
content = obj("application/json", obj("schema", obj()))
default:
content = obj("application/json", obj("schema", g.schema(reflect.TypeOf(r.Response))))
}
if r.CSV {
content.set("text/csv", obj("schema", obj("type", "string")))
}
if r.Stream {
content.set("text/event-stream", obj("schema", obj("type", "string",
"description", "With stream: true, server-sent events: one JSON chunk per data: line, then data: [DONE].")))
}
desc := "OK"
if status == 202 {
desc = "Accepted: started, and running on."
@@ -226,10 +301,10 @@ func (g *generator) operation(r adminapi.Route, pathParams map[string]string) (o
}
// operationID is the method and the path's words, getModelsNameTarget.
func operationID(method, p string) string {
func (g *generator) operationID(method, p string) string {
var b strings.Builder
b.WriteString(strings.ToLower(method))
for _, s := range strings.Split(strings.TrimPrefix(p, "/api/v1/"), "/") {
for _, s := range strings.Split(strings.TrimPrefix(p, g.d.Prefix), "/") {
for _, w := range strings.FieldsFunc(s, func(r rune) bool { return !unicode.IsLetter(r) && !unicode.IsDigit(r) }) {
b.WriteString(strings.ToUpper(w[:1]) + w[1:])
}
@@ -238,8 +313,8 @@ func operationID(method, p string) string {
}
// tagOf groups an operation by the first word of its path.
func tagOf(p string) string {
first, _, _ := strings.Cut(strings.TrimPrefix(p, "/api/v1/"), "/")
func (g *generator) tagOf(p string) string {
first, _, _ := strings.Cut(strings.TrimPrefix(strings.TrimPrefix(p, g.d.Prefix), "/"), "/")
return strings.TrimSuffix(first, ".json")
}
@@ -256,13 +331,13 @@ type generator struct {
names map[reflect.Type]string
schemas map[string]any
seen []reflect.Type
d Doc
}
var (
timeType = reflect.TypeOf(time.Time{})
durationType = reflect.TypeOf(time.Duration(0))
rawType = reflect.TypeOf(json.RawMessage{})
errorType = reflect.TypeOf(adminapi.ErrorView{})
marshalerType = reflect.TypeOf((*json.Marshaler)(nil)).Elem()
textType = reflect.TypeOf((*encoding.TextMarshaler)(nil)).Elem()
)
@@ -294,7 +369,7 @@ func (g *generator) collect(t reflect.Type) {
// modelserve.Job. Qualified always rather than only on a collision, so a
// type added elsewhere one day cannot rename a schema clients already use.
func (g *generator) assignNames() {
own := reflect.TypeOf(adminapi.Route{}).PkgPath()
own := g.d.Home
for _, t := range g.seen {
n := t.Name()
if t.PkgPath() != own {
+37
View File
@@ -8,6 +8,7 @@ import (
"strings"
"testing"
"gitea.mynodes.xyz/ilker/llmgw/internal/clientapi"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
)
@@ -161,3 +162,39 @@ func TestAPathParameterWithNoDescriptionIsAnError(t *testing.T) {
t.Error("a parameter nobody described was let through")
}
}
func TestTheClientAPIDocumentIsNotStaleAndDescribesWhatClientsSend(t *testing.T) {
want, err := GenerateDoc(repoRoot(t), Client, clientapi.Routes, clientapi.PathParams)
if err != nil {
t.Fatal(err)
}
got, err := os.ReadFile(filepath.Join(repoRoot(t), "docs", "client-api.openapi.json"))
if err != nil || string(got) != string(want) {
t.Fatal("docs/client-api.openapi.json no longer matches the client API's routes and types.\n" +
"Run: go generate ./internal/docgen")
}
var doc map[string]any
if err := json.Unmarshal(want, &doc); err != nil {
t.Fatal(err)
}
chat := at(t, doc, "paths", "/v1/chat/completions", "post")
if at(t, chat, "requestBody", "content", "application/json", "schema", "$ref") != "#/components/schemas/ChatCompletionRequest" {
t.Error("chat's body is not its request type")
}
if _, ok := at(t, chat, "responses", "200", "content").(map[string]any)["text/event-stream"]; !ok {
t.Error("chat does not say it may stream")
}
if _, ok := at(t, doc, "paths", "/v1/files", "post", "requestBody", "content").(map[string]any)["multipart/form-data"]; !ok {
t.Error("an upload is not a form")
}
if at(t, doc, "paths", "/v1/3d/generations", "post", "responses", "202", "description") == nil {
t.Error("a 3D job is not answered 202")
}
if _, ok := at(t, doc, "components", "securitySchemes").(map[string]any)["apiKey"]; !ok {
t.Error("no API key scheme")
}
// The admin API's actor header is the admin API's.
if _, ok := at(t, doc, "components").(map[string]any)["parameters"]; ok {
t.Error("the client API takes the admin API's X-Llmgw-Actor")
}
}