The client API described in OpenAPI, and both APIs in Swagger UI
/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:
1 parent
41601bc5ef
commit
fd3c7bda32
26 files changed
+3956
-48
No files matched your search
@@ -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 {
|
||||
|
||||
Reference in new issue
Block a user