mirror of
https://github.com/zap-proto/zip.git
synced 2026-10-19 15:38:57 +00:00
zeekayandHanzo Dev
5f71d2496b
App, Group, Operation. A group is a prefix and what holds under it, an operation
is one typed route declared there, and the verb methods are generic methods —
which Go 1.27 allows on a concrete type and still refuses on an interface. So In
and Out come from the handler and the caller writes no type arguments:
users := app.Group("/v1/users")
users.Post("/", api.Create)
mint := users.Group("/mint").With(middleware.Mint(gate))
mint.Post("/deposit", api.Deposit)
A Group is a CLOSED HANDLE: two unexported fields, and no method that hands back
the app, the parent or the fiber underneath. A subsystem given the group at its
own prefix cannot reach above it, so confinement is a property of the type
instead of a rule something has to police — which is what a host needs in order
to hand out a bounded surface and know what comes back.
That is bought by giving up the router interface, deliberately. Router and
OpTarget are gone, and with them the ability to implement a route table outside
this package: a decorator is no longer a router, a gate is middleware on a group,
and a bound is a path. The five package-level verb functions go the same way —
a registration is a method on the thing it registers into.
Raw carries what is not a typed operation: a stream, an upgrade, a probe, a
foreign subtree. It names its method, and it is the longer spelling because
opting out of the typed model is the exception and should read like one.
Co-authored-by: Hanzo Dev <[email protected]>
68 lines
2.2 KiB
Go
68 lines
2.2 KiB
Go
package zip_test
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"strings"
|
|
"testing"
|
|
|
|
"github.com/zap-proto/zip"
|
|
)
|
|
|
|
type invIn struct {
|
|
Limit int `json:"limit"`
|
|
Org string `json:"org" validate:"required"`
|
|
}
|
|
type invOut struct {
|
|
Invoices []string `json:"invoices"`
|
|
}
|
|
|
|
// TestDoc_ReachesTheSpec proves an extracted doc comment becomes the operation's
|
|
// description, its fields' descriptions, and its request/response examples —
|
|
// i.e. that the comment IS the spec rather than something written twice.
|
|
func TestDoc_ReachesTheSpec(t *testing.T) {
|
|
app := zip.New(zip.Config{DisableStartupMessage: true})
|
|
|
|
// What cmd/zipdoc emits for this operation.
|
|
zip.Describe("POST /v1/billing/invoices", zip.Doc{
|
|
Description: "ListInvoices returns every invoice for the caller's org, newest first. Results are capped by limit.",
|
|
Fields: map[string]string{
|
|
"invIn.limit": "Maximum invoices to return.",
|
|
"invIn.org": "Org whose invoices to list.",
|
|
"invOut.invoices": "Invoice ids, newest first.",
|
|
},
|
|
Example: json.RawMessage(`{"limit":25,"org":"hanzo"}`),
|
|
Response: json.RawMessage(`{"invoices":["inv_2","inv_1"]}`),
|
|
})
|
|
app.Post("/v1/billing/invoices", func(_ context.Context, in *invIn) (*invOut, error) {
|
|
return &invOut{}, nil
|
|
})
|
|
|
|
spec := app.OpenAPISpec()
|
|
raw, err := json.Marshal(spec)
|
|
if err != nil {
|
|
t.Fatalf("marshal spec: %v", err)
|
|
}
|
|
got := string(raw)
|
|
|
|
for _, want := range []string{
|
|
`newest first`, // description
|
|
`Maximum invoices to return.`, // In field doc
|
|
`Invoice ids, newest first.`, // Out field doc
|
|
`"limit":25`, // request example
|
|
`"invoices":["inv_2","inv_1"]`, // response example
|
|
} {
|
|
if !strings.Contains(got, want) {
|
|
t.Errorf("spec is missing %q", want)
|
|
}
|
|
}
|
|
|
|
// The summary falls back to the comment's first sentence, which Go's own
|
|
// convention already makes a summary — so nobody writes it twice.
|
|
ops := spec["paths"].(map[string]map[string]any)["/v1/billing/invoices"]
|
|
post := ops["post"].(map[string]any)
|
|
if s, _ := post["summary"].(string); !strings.HasPrefix(s, "ListInvoices returns") || strings.Contains(s, "capped by limit") {
|
|
t.Errorf("summary = %q, want just the first sentence", s)
|
|
}
|
|
}
|