feat: declare API errors and authentication with developer tooling

examples/userService/api/user.api

@@ -3,6 +3,20 @@ info (
  title: "User service reference"
  version: "1.0.0"
 )
+// Stable public errors are shared by Go code and the API document.
+error (
+ Unauthenticated 401 "UNAUTHENTICATED" "authentication required"
+ Forbidden 403 "FORBIDDEN" "permission denied"
+ UserNotFound 404 "USER_NOT_FOUND" "user not found"
+ EmailTaken 409 "EMAIL_TAKEN" "email already in use"
+ InvalidUser 400 "INVALID_USER" "invalid user"
+ InvalidPage 400 "INVALID_PAGE" "invalid pagination"
+)
+auth AdminAuth (
+ type: bearer
+ middleware: Auth
+ description: "Use an administrator token for writes, or a read-only token for GET requests"
+)
 type (
  UserResp {
   ID int64 `json:"id"`
@@ -40,21 +54,33 @@ type (
 @server (
  group: user
  prefix: /api/v1
- middleware: Auth
+ auth: AdminAuth
+ errors: Unauthenticated
 )
 service user-api {
+ @doc (
+  summary: "Create a user"
+  description: "Normalizes the email, then commits user data and audit in one transaction"
+  tags: users
+ )
+ @errors Forbidden, InvalidUser, EmailTaken
  @handler createUser
  @status 201
  post /users (CreateUserReq) returns (UserResp)
+ @errors UserNotFound
  @handler getUser
  get /users/:id (UserIDReq) returns (UserResp)
+ @errors InvalidPage
  @handler listUsers
  get /users (ListUsersReq) returns (UserPageResp)
+ @errors Forbidden, InvalidUser, UserNotFound, EmailTaken
  @handler updateUser
  put /users/:id (UpdateUserReq) returns (UserResp)
+ @errors Forbidden, UserNotFound
  @handler deleteUser
  delete /users/:id (UserIDReq)
  @doc "Export one user as a private text object with a short-lived download link"
+ @errors Forbidden, UserNotFound
  @handler exportUser
  post /users/:id/export (UserIDReq) returns (ExportResp)
 }