Ilker ManapandClaude Opus 5.5
a95c519bc5
adminapi.Routes lists every endpoint with its query parameters and Go values
of the bodies it reads and answers with; internal/docgen/openapi turns that
into docs/admin-api.openapi.json by reflection, the way encoding/json encodes
the types, with the fields' comments as descriptions. A test fails when an
endpoint is registered and not in the table, another when the committed
document is stale. The binary embeds it and serves it with the token.
Handlers that wrote map literals and decoded anonymous structs now use named
types, so the document can see them. GET /api/v1/models/{name} answers with a
model's whole definition as it is in force, which a tool managing it needs.
docs/admin-api.md: reaching the API, the token, what a request must carry.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
61 lines
1.9 KiB
Go
61 lines
1.9 KiB
Go
// Command gen writes docs/reference.md from the configuration structs, and
|
|
// docs/admin-api.openapi.json from the admin API route table.
|
|
//
|
|
// Run by `go generate ./...`, and checked by a test, so the reference cannot
|
|
// quietly stop describing the code.
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
"os"
|
|
"path/filepath"
|
|
"runtime"
|
|
|
|
"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
|
|
"gitea.mynodes.xyz/ilker/llmgw/internal/docgen"
|
|
"gitea.mynodes.xyz/ilker/llmgw/internal/docgen/openapi"
|
|
)
|
|
|
|
func main() {
|
|
// The repository root, found from this file rather than from the working
|
|
// directory, so `go generate ./...` produces the same document wherever
|
|
// it is run from.
|
|
_, self, _, ok := runtime.Caller(0)
|
|
if !ok {
|
|
fmt.Fprintln(os.Stderr, "error: cannot locate the generator")
|
|
os.Exit(1)
|
|
}
|
|
root := filepath.Join(filepath.Dir(self), "..", "..", "..")
|
|
|
|
paths := make([]string, len(docgen.Sources))
|
|
for i, s := range docgen.Sources {
|
|
paths[i] = filepath.Join(root, s)
|
|
}
|
|
|
|
blocks, err := docgen.Collect(paths)
|
|
if err != nil {
|
|
fmt.Fprintln(os.Stderr, "error:", err)
|
|
os.Exit(1)
|
|
}
|
|
if err := os.WriteFile(filepath.Join(root, "docs", "reference.md"), []byte(docgen.Render(blocks)), 0o644); err != nil {
|
|
fmt.Fprintln(os.Stderr, "error:", err)
|
|
os.Exit(1)
|
|
}
|
|
if err := os.WriteFile(filepath.Join(root, "internal", "docgen", "reference_gen.go"), []byte(docgen.RenderGo(blocks)), 0o644); err != nil {
|
|
fmt.Fprintln(os.Stderr, "error:", err)
|
|
os.Exit(1)
|
|
}
|
|
fmt.Printf("docs/reference.md and internal/docgen/reference_gen.go: %d blocks\n", len(blocks))
|
|
|
|
spec, err := openapi.Generate(root, adminapi.Routes, adminapi.PathParams)
|
|
if err != nil {
|
|
fmt.Fprintln(os.Stderr, "error:", err)
|
|
os.Exit(1)
|
|
}
|
|
if err := os.WriteFile(filepath.Join(root, "docs", "admin-api.openapi.json"), spec, 0o644); err != nil {
|
|
fmt.Fprintln(os.Stderr, "error:", err)
|
|
os.Exit(1)
|
|
}
|
|
fmt.Printf("docs/admin-api.openapi.json: %d routes\n", len(adminapi.Routes))
|
|
}
|