feat: complete API-driven projects with infrastructure and business acceptance

examples/contracts/user.api

@@ -0,0 +1,58 @@
+syntax = "v1"
+
+info (
+    title: "User API"
+    version: "1.0.0"
+)
+
+import "shared.api"
+
+type (
+    UpdateUserReq {
+        UserID int64 `path:"userId,range=[1:1000000]"`
+        Notify bool `form:"notify,default=false"`
+        Client string `header:"X-Client,optional"`
+        Name string `json:"name" binding:"required,max=50"`
+        Active bool `json:"active"`
+        Age *int `json:"age,optional,range=[0:150]"`
+        Address *Address `json:"address,optional"`
+    }
+    ListUsersReq {
+        Page int `form:"page,default=1,range=[1:1000]"`
+        PageSize int `form:"pageSize,default=20,range=[1:100]"`
+        Tags []string `form:"tag,optional" binding:"max=10"`
+    }
+    ListUsersResp {
+        Items []UserResp `json:"items"`
+        Page int `json:"page"`
+        Total int64 `json:"total"`
+    }
+    DeleteUserReq {
+        UserID int64 `path:"userId,range=[1:1000000]"`
+    }
+)
+
+@server (
+    group: user
+    prefix: /api/v1
+)
+service user-api {
+    @doc "Update a user"
+    @handler updateUser
+    put /users/:userId (UpdateUserReq) returns (UserResp)
+
+    @doc "List users"
+    @handler listUsers
+    get /users (ListUsersReq) returns (ListUsersResp)
+}
+
+@server (
+    group: admin/user
+    prefix: /admin/v1
+    middleware: Auth,Audit
+)
+service user-api {
+    @doc "Delete a user; business-owned authentication and auditing required"
+    @handler deleteUser
+    delete /users/:userId (DeleteUserReq)
+}