core/api
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

feat(openapi): add terms of service metadata

Browse source 
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Virgil 2026-04-01 20:44:01 +00:00
parent 071de51bb5
commit 4d7f3a9f99
10 changed files with 187 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
api.go
View file

@ -25,24 +25,25 @@ const shutdownTimeout = 10 * time.Second
// Engine is the central API server managing route groups and middleware.
type Engine struct {
addr string
groups []RouteGroup
middlewares []gin.HandlerFunc
wsHandler http.Handler
sseBroker *SSEBroker
swaggerEnabled bool
swaggerTitle string
swaggerDesc string
swaggerVersion string
swaggerServers []string
swaggerContactName string
swaggerContactURL string
swaggerContactEmail string
swaggerLicenseName string
swaggerLicenseURL string
pprofEnabled bool
expvarEnabled bool
graphql *graphqlConfig
addr string
groups []RouteGroup
middlewares []gin.HandlerFunc
wsHandler http.Handler
sseBroker *SSEBroker
swaggerEnabled bool
swaggerTitle string
swaggerDesc string
swaggerVersion string
swaggerTermsOfService string
swaggerServers []string
swaggerContactName string
swaggerContactURL string
swaggerContactEmail string
swaggerLicenseName string
swaggerLicenseURL string
pprofEnabled bool
expvarEnabled bool
graphql *graphqlConfig
}
// New creates an Engine with the given options.
@ -195,6 +196,7 @@ func (e *Engine) build() *gin.Engine {
e.swaggerTitle,
e.swaggerDesc,
e.swaggerVersion,
e.swaggerTermsOfService,
e.swaggerContactName,
e.swaggerContactURL,
e.swaggerContactEmail,

25
cmd/api/cmd_sdk.go
View file

@ -31,6 +31,7 @@ func addSDKCommand(parent *cli.Command) {
title string
description string
version string
termsURL string
contactName string
contactURL string
contactEmail string
@ -47,7 +48,7 @@ func addSDKCommand(parent *cli.Command) {
// If no spec file provided, generate one to a temp file.
if specFile == "" {
builder := sdkSpecBuilder(title, description, version, contactName, contactURL, contactEmail, licenseName, licenseURL, servers)
builder := sdkSpecBuilder(title, description, version, termsURL, contactName, contactURL, contactEmail, licenseName, licenseURL, servers)
groups := sdkSpecGroups()
tmpFile, err := os.CreateTemp("", "openapi-*.json")
@ -96,6 +97,7 @@ func addSDKCommand(parent *cli.Command) {
cli.StringFlag(cmd, &title, "title", "t", defaultSDKTitle, "API title in generated spec")
cli.StringFlag(cmd, &description, "description", "d", defaultSDKDescription, "API description in generated spec")
cli.StringFlag(cmd, &version, "version", "V", defaultSDKVersion, "API version in generated spec")
cli.StringFlag(cmd, &termsURL, "terms-of-service", "", "", "OpenAPI terms of service URL in generated spec")
cli.StringFlag(cmd, &contactName, "contact-name", "", "", "OpenAPI contact name in generated spec")
cli.StringFlag(cmd, &contactURL, "contact-url", "", "", "OpenAPI contact URL in generated spec")
cli.StringFlag(cmd, &contactEmail, "contact-email", "", "", "OpenAPI contact email in generated spec")
@ -106,17 +108,18 @@ func addSDKCommand(parent *cli.Command) {
parent.AddCommand(cmd)
}
func sdkSpecBuilder(title, description, version, contactName, contactURL, contactEmail, licenseName, licenseURL, servers string) *goapi.SpecBuilder {
func sdkSpecBuilder(title, description, version, termsURL, contactName, contactURL, contactEmail, licenseName, licenseURL, servers string) *goapi.SpecBuilder {
return &goapi.SpecBuilder{
Title: title,
Description: description,
Version: version,
ContactName: contactName,
ContactURL: contactURL,
ContactEmail: contactEmail,
Servers: parseServers(servers),
LicenseName: licenseName,
LicenseURL: licenseURL,
Title: title,
Description: description,
Version: version,
TermsOfService: termsURL,
ContactName: contactName,
ContactURL: contactURL,
ContactEmail: contactEmail,
Servers: parseServers(servers),
LicenseName: licenseName,
LicenseURL: licenseURL,
}
}

21
cmd/api/cmd_spec.go
View file

@ -18,6 +18,7 @@ func addSpecCommand(parent *cli.Command) {
title string
description string
version string
termsURL string
contactName string
contactURL string
contactEmail string
@ -29,15 +30,16 @@ func addSpecCommand(parent *cli.Command) {
cmd := cli.NewCommand("spec", "Generate OpenAPI specification", "", func(cmd *cli.Command, args []string) error {
// Build spec from all route groups registered for CLI generation.
builder := &goapi.SpecBuilder{
Title: title,
Description: description,
Version: version,
ContactName: contactName,
ContactURL: contactURL,
ContactEmail: contactEmail,
Servers: parseServers(servers),
LicenseName: licenseName,
LicenseURL: licenseURL,
Title: title,
Description: description,
Version: version,
TermsOfService: termsURL,
ContactName: contactName,
ContactURL: contactURL,
ContactEmail: contactEmail,
Servers: parseServers(servers),
LicenseName: licenseName,
LicenseURL: licenseURL,
}
bridge := goapi.NewToolBridge("/tools")
@ -59,6 +61,7 @@ func addSpecCommand(parent *cli.Command) {
cli.StringFlag(cmd, &title, "title", "t", "Lethean Core API", "API title in spec")
cli.StringFlag(cmd, &description, "description", "d", "Lethean Core API", "API description in spec")
cli.StringFlag(cmd, &version, "version", "V", "1.0.0", "API version in spec")
cli.StringFlag(cmd, &termsURL, "terms-of-service", "", "", "OpenAPI terms of service URL in spec")
cli.StringFlag(cmd, &contactName, "contact-name", "", "", "OpenAPI contact name in spec")
cli.StringFlag(cmd, &contactURL, "contact-url", "", "", "OpenAPI contact URL in spec")
cli.StringFlag(cmd, &contactEmail, "contact-email", "", "", "OpenAPI contact email in spec")

46
cmd/api/cmd_test.go
View file

@ -82,6 +82,9 @@ func TestAPISpecCmd_Good_JSON(t *testing.T) {
if specCmd.Flag("version") == nil {
t.Fatal("expected --version flag on spec command")
}
if specCmd.Flag("terms-of-service") == nil {
t.Fatal("expected --terms-of-service flag on spec command")
}
if specCmd.Flag("contact-name") == nil {
t.Fatal("expected --contact-name flag on spec command")
}
@ -180,6 +183,41 @@ func TestAPISpecCmd_Good_ContactFlagsPopulateSpecInfo(t *testing.T) {
}
}
func TestAPISpecCmd_Good_TermsOfServiceFlagPopulatesSpecInfo(t *testing.T) {
root := &cli.Command{Use: "root"}
AddAPICommands(root)
outputFile := t.TempDir() + "/spec.json"
root.SetArgs([]string{
"api", "spec",
"--terms-of-service", "https://example.com/terms",
"--output", outputFile,
})
root.SetErr(new(bytes.Buffer))
if err := root.Execute(); err != nil {
t.Fatalf("unexpected error: %v", err)
}
data, err := os.ReadFile(outputFile)
if err != nil {
t.Fatalf("expected spec file to be written: %v", err)
}
var spec map[string]any
if err := json.Unmarshal(data, &spec); err != nil {
t.Fatalf("expected valid JSON spec, got error: %v", err)
}
info, ok := spec["info"].(map[string]any)
if !ok {
t.Fatal("expected info object in generated spec")
}
if info["termsOfService"] != "https://example.com/terms" {
t.Fatalf("expected termsOfService to be preserved, got %v", info["termsOfService"])
}
}
func TestAPISpecCmd_Good_ServerFlagAddsServers(t *testing.T) {
root := &cli.Command{Use: "root"}
AddAPICommands(root)
@ -361,6 +399,9 @@ func TestAPISDKCmd_Good_ValidatesLanguage(t *testing.T) {
if sdkCmd.Flag("version") == nil {
t.Fatal("expected --version flag on sdk command")
}
if sdkCmd.Flag("terms-of-service") == nil {
t.Fatal("expected --terms-of-service flag on sdk command")
}
if sdkCmd.Flag("contact-name") == nil {
t.Fatal("expected --contact-name flag on sdk command")
}
@ -395,6 +436,7 @@ func TestAPISDKCmd_Good_TempSpecUsesMetadataFlags(t *testing.T) {
"Custom SDK API",
"Custom SDK description",
"9.9.9",
"https://example.com/terms",
"SDK Support",
"https://example.com/support",
"support@example.com",
@ -433,6 +475,10 @@ func TestAPISDKCmd_Good_TempSpecUsesMetadataFlags(t *testing.T) {
t.Fatalf("expected custom version, got %v", info["version"])
}
if info["termsOfService"] != "https://example.com/terms" {
t.Fatalf("expected termsOfService to be preserved, got %v", info["termsOfService"])
}
contact, ok := info["contact"].(map[string]any)
if !ok {
t.Fatal("expected contact metadata in generated spec")

2
docs/architecture.md
View file

@ -162,6 +162,8 @@ They execute after `gin.Recovery()` but before any route handler. The `Option` t
| `WithWSHandler(h)` | WebSocket at `/ws` | Wraps any `http.Handler` |
| `WithAuthentik(cfg)` | Authentik forward-auth + OIDC JWT | Permissive; populates context, never rejects |
| `WithSwagger(title, desc, ver)` | Swagger UI at `/swagger/` | Runtime spec via `SpecBuilder` |
| `WithSwaggerTermsOfService(url)` | OpenAPI terms of service metadata | Populates the Swagger spec info block without manual `SpecBuilder` wiring |
| `WithSwaggerContact(name, url, email)` | OpenAPI contact metadata | Populates the Swagger spec info block without manual `SpecBuilder` wiring |
| `WithSwaggerServers(servers...)` | OpenAPI server metadata | Feeds the runtime Swagger spec and exported docs |
| `WithSwaggerLicense(name, url)` | OpenAPI licence metadata | Populates the Swagger spec info block without manual `SpecBuilder` wiring |
| `WithPprof()` | Go profiling at `/debug/pprof/` | WARNING: do not expose in production without authentication |

23
openapi.go
View file

@ -19,15 +19,16 @@ import (
// builder := &api.SpecBuilder{Title: "Service", Version: "1.0.0"}
// spec, err := builder.Build(engine.Groups())
type SpecBuilder struct {
Title string
Description string
Version string
ContactName string
ContactURL string
ContactEmail string
Servers []string
LicenseName string
LicenseURL string
Title string
Description string
Version string
TermsOfService string
ContactName string
ContactURL string
ContactEmail string
Servers []string
LicenseName string
LicenseURL string
}
// Build generates the complete OpenAPI 3.1 JSON spec.
@ -64,6 +65,10 @@ func (sb *SpecBuilder) Build(groups []RouteGroup) ([]byte, error) {
spec["info"].(map[string]any)["license"] = license
}
if sb.TermsOfService != "" {
spec["info"].(map[string]any)["termsOfService"] = sb.TermsOfService
}
if sb.ContactName != "" || sb.ContactURL != "" || sb.ContactEmail != "" {
contact := map[string]any{}
if sb.ContactName != "" {

24
openapi_test.go
View file

@ -214,6 +214,30 @@ func TestSpecBuilder_Good_InfoIncludesContactMetadata(t *testing.T) {
}
}
func TestSpecBuilder_Good_InfoIncludesTermsOfService(t *testing.T) {
sb := &api.SpecBuilder{
Title: "Test",
Description: "Terms test API",
Version: "1.2.3",
TermsOfService: "https://example.com/terms",
}
data, err := sb.Build(nil)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
var spec map[string]any
if err := json.Unmarshal(data, &spec); err != nil {
t.Fatalf("invalid JSON: %v", err)
}
info := spec["info"].(map[string]any)
if info["termsOfService"] != "https://example.com/terms" {
t.Fatalf("expected termsOfService to be preserved, got %v", info["termsOfService"])
}
}
func TestSpecBuilder_Good_WithDescribableGroup(t *testing.T) {
sb := &api.SpecBuilder{
Title: "Test",

8
options.go
View file

@ -129,6 +129,14 @@ func WithSwagger(title, description, version string) Option {
}
}
// WithSwaggerTermsOfService adds the terms of service URL to the generated Swagger spec.
// Empty strings are ignored.
func WithSwaggerTermsOfService(url string) Option {
return func(e *Engine) {
e.swaggerTermsOfService = url
}
}
// WithSwaggerContact adds contact metadata to the generated Swagger spec.
// Empty fields are ignored. Multiple calls replace the previous contact data.
func WithSwaggerContact(name, url, email string) Option {

21
swagger.go
View file

@ -40,18 +40,19 @@ func (s *swaggerSpec) ReadDoc() string {
}
// registerSwagger mounts the Swagger UI and doc.json endpoint.
func registerSwagger(g *gin.Engine, title, description, version, contactName, contactURL, contactEmail string, servers []string, licenseName, licenseURL string, groups []RouteGroup) {
func registerSwagger(g *gin.Engine, title, description, version, termsOfService, contactName, contactURL, contactEmail string, servers []string, licenseName, licenseURL string, groups []RouteGroup) {
spec := &swaggerSpec{
builder: &SpecBuilder{
Title: title,
Description: description,
Version: version,
ContactName: contactName,
ContactURL: contactURL,
ContactEmail: contactEmail,
Servers: servers,
LicenseName: licenseName,
LicenseURL: licenseURL,
Title: title,
Description: description,
Version: version,
TermsOfService: termsOfService,
ContactName: contactName,
ContactURL: contactURL,
ContactEmail: contactEmail,
Servers: servers,
LicenseName: licenseName,
LicenseURL: licenseURL,
},
groups: groups,
}

36
swagger_test.go
View file

@ -347,6 +347,42 @@ func TestSwagger_Good_UsesContactMetadata(t *testing.T) {
}
}
func TestSwagger_Good_UsesTermsOfServiceMetadata(t *testing.T) {
gin.SetMode(gin.TestMode)
e, err := api.New(
api.WithSwagger("Terms API", "Terms test", "1.0.0"),
api.WithSwaggerTermsOfService("https://example.com/terms"),
)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
srv := httptest.NewServer(e.Handler())
defer srv.Close()
resp, err := http.Get(srv.URL + "/swagger/doc.json")
if err != nil {
t.Fatalf("request failed: %v", err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
t.Fatalf("failed to read body: %v", err)
}
var doc map[string]any
if err := json.Unmarshal(body, &doc); err != nil {
t.Fatalf("invalid JSON: %v", err)
}
info := doc["info"].(map[string]any)
if info["termsOfService"] != "https://example.com/terms" {
t.Fatalf("expected termsOfService=%q, got %v", "https://example.com/terms", info["termsOfService"])
}
}
func TestSwagger_Good_UsesServerMetadata(t *testing.T) {
gin.SetMode(gin.TestMode)