better API docs

Author: hugodutka

lib/httpapi/events.go

@@ -8,6 +8,8 @@ import (
 
 	mf "github.com/coder/agentapi/lib/msgfmt"
 	st "github.com/coder/agentapi/lib/screentracker"
+	"github.com/coder/agentapi/lib/util"
+	"github.com/danielgtaylor/huma/v2"
 )
 
 type EventType string
@@ -21,19 +23,28 @@ const (
 type AgentStatus string
 
 const (
-	AgentStatusStable  AgentStatus = "stable"
 	AgentStatusRunning AgentStatus = "running"
+	AgentStatusStable  AgentStatus = "stable"
 )
 
+var AgentStatusValues = []AgentStatus{
+	AgentStatusStable,
+	AgentStatusRunning,
+}
+
+func (a AgentStatus) Schema(r huma.Registry) *huma.Schema {
+	return util.OpenAPISchema(r, "AgentStatus", AgentStatusValues)
+}
+
 type MessageUpdateBody struct {
-	Id      int                 `json:"id"`
-	Role    st.ConversationRole `json:"role"`
-	Message string              `json:"message"`
-	Time    time.Time           `json:"time"`
+	Id      int                 `json:"id" doc:"Unique identifier for the message. This identifier also represents the order of the message in the conversation history."`
+	Role    st.ConversationRole `json:"role" doc:"Role of the message author"`
+	Message string              `json:"message" doc:"Message content"`
+	Time    time.Time           `json:"time" doc:"Timestamp of the message"`
 }
 
 type StatusChangeBody struct {
-	Status AgentStatus `json:"status"`
+	Status AgentStatus `json:"status" doc:"Agent status"`
 }
 
 type ScreenUpdateBody struct {

lib/httpapi/models.go

@@ -1,45 +1,60 @@
 package httpapi
 
+import (
+	st "github.com/coder/agentapi/lib/screentracker"
+	"github.com/coder/agentapi/lib/util"
+	"github.com/danielgtaylor/huma/v2"
+)
+
 type MessageType string
 
 const (
 	MessageTypeUser MessageType = "user"
 	MessageTypeRaw  MessageType = "raw"
 )
 
+var MessageTypeValues = []MessageType{
+	MessageTypeUser,
+	MessageTypeRaw,
+}
+
+func (m MessageType) Schema(r huma.Registry) *huma.Schema {
+	return util.OpenAPISchema(r, "MessageType", MessageTypeValues)
+}
+
 // Message represents a message
 type Message struct {
-	Content string `json:"content" example:"Hello world" doc:"Message content"`
-	Role    string `json:"role" example:"user" doc:"Role of the message author"`
+	Content string              `json:"content" example:"Hello world" doc:"Message content"`
+	Role    st.ConversationRole `json:"role" doc:"Role of the message author"`
 }
 
 // StatusResponse represents the server status
 type StatusResponse struct {
 	Body struct {
-		Status string `json:"status" example:"running" doc:"Current server status"`
+		Status AgentStatus `json:"status" doc:"Current agent status. 'running' means that the agent is processing a message, 'stable' means that the agent is idle and waiting for input."`
 	}
 }
 
 // MessagesResponse represents the list of messages
 type MessagesResponse struct {
 	Body struct {
-		Messages []Message `json:"messages" doc:"List of messages"`
+		Messages []Message `json:"messages" nullable:"false" doc:"List of messages"`
 	}
 }
 
 type MessageRequestBody struct {
-	Content string      `json:"content" example:"Hello, server!" doc:"Message content"`
-	Type    MessageType `json:"type" enum:"user,raw" example:"user" doc:"Type of the message"`
+	Content string      `json:"content" example:"Hello, agent!" doc:"Message content"`
+	Type    MessageType `json:"type" doc:"A 'user' type message will be logged as a user message in the conversation history and submitted to the agent. AgentAPI will wait until the agent starts carrying out the task described in the message before responding. A 'raw' type message will be written directly to the agent's terminal session as keystrokes and will not be saved in the conversation history. 'raw' messages are useful for sending escape sequences to the terminal."`
 }
 
 // MessageRequest represents a request to create a new message
 type MessageRequest struct {
-	Body MessageRequestBody `json:"body"`
+	Body MessageRequestBody `json:"body" doc:"Message content and type"`
 }
 
 // MessageResponse represents a newly created message
 type MessageResponse struct {
 	Body struct {
-		Ok bool `json:"ok" doc:"Whether the message was sent successfully"`
+		Ok bool `json:"ok" doc:"Indicates whether the message was sent successfully. For messages of type 'user', success means detecting that the agent began executing the task described. For messages of type 'raw', success means the keystrokes were sent to the terminal."`
 	}
 }

lib/httpapi/server.go

@@ -98,20 +98,27 @@ func NewServer(ctx context.Context, agentType mf.AgentType, process *termexec.Pr
 // registerRoutes sets up all API endpoints
 func (s *Server) registerRoutes() {
 	// GET /status endpoint
-	huma.Get(s.api, "/status", s.getStatus)
+	huma.Get(s.api, "/status", s.getStatus, func(o *huma.Operation) {
+		o.Description = "Returns the current status of the agent."
+	})
 
 	// GET /messages endpoint
-	huma.Get(s.api, "/messages", s.getMessages)
+	huma.Get(s.api, "/messages", s.getMessages, func(o *huma.Operation) {
+		o.Description = "Returns a list of messages representing the conversation history with the agent."
+	})
 
 	// POST /message endpoint
-	huma.Post(s.api, "/message", s.createMessage)
+	huma.Post(s.api, "/message", s.createMessage, func(o *huma.Operation) {
+		o.Description = "Send a message to the agent. For messages of type 'user', the agent's status must be 'stable' for the operation to complete successfully. Otherwise, this endpoint will return an error."
+	})
 
 	// GET /events endpoint
 	sse.Register(s.api, huma.Operation{
 		OperationID: "subscribeEvents",
 		Method:      http.MethodGet,
 		Path:        "/events",
 		Summary:     "Subscribe to events",
+		Description: "The events are sent as Server-Sent Events (SSE). Initially, the endpoint returns a list of events needed to reconstruct the current state of the conversation and the agent's status. After that, it only returns events that have occurred since the last event was sent.",
 	}, map[string]any{
 		// Mapping of event type name to Go struct for that event.
 		"message_update": MessageUpdateBody{},
@@ -138,7 +145,7 @@ func (s *Server) getStatus(ctx context.Context, input *struct{}) (*StatusRespons
 	agentStatus := convertStatus(status)
 
 	resp := &StatusResponse{}
-	resp.Body.Status = string(agentStatus)
+	resp.Body.Status = agentStatus
 
 	return resp, nil
 }
@@ -152,7 +159,7 @@ func (s *Server) getMessages(ctx context.Context, input *struct{}) (*MessagesRes
 	resp.Body.Messages = make([]Message, len(s.conversation.Messages()))
 	for i, msg := range s.conversation.Messages() {
 		resp.Body.Messages[i] = Message{
-			Role:    string(msg.Role),
+			Role:    msg.Role,
 			Content: msg.Message,
 		}
 	}

lib/screentracker/conversation.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/coder/agentapi/lib/msgfmt"
 	"github.com/coder/agentapi/lib/util"
+	"github.com/danielgtaylor/huma/v2"
 	"golang.org/x/xerrors"
 )
 
@@ -48,6 +49,15 @@ const (
 	ConversationRoleAgent ConversationRole = "agent"
 )
 
+var ConversationRoleValues = []ConversationRole{
+	ConversationRoleUser,
+	ConversationRoleAgent,
+}
+
+func (c ConversationRole) Schema(r huma.Registry) *huma.Schema {
+	return util.OpenAPISchema(r, "ConversationRole", ConversationRoleValues)
+}
+
 type ConversationMessage struct {
 	Id      int
 	Message string

lib/util/util.go

@@ -2,8 +2,11 @@ package util
 
 import (
 	"context"
+	"fmt"
+	"reflect"
 	"time"
 
+	"github.com/danielgtaylor/huma/v2"
 	"golang.org/x/xerrors"
 )
 
@@ -60,3 +63,17 @@ func WaitFor(ctx context.Context, timeout WaitTimeout, condition func() (bool, e
 		}
 	}
 }
+
+// based on https://github.com/danielgtaylor/huma/issues/621#issuecomment-2456588788
+func OpenAPISchema[T ~string](r huma.Registry, enumName string, values []T) *huma.Schema {
+	if r.Map()[enumName] == nil {
+		schemaRef := r.Schema(reflect.TypeOf(""), true, enumName)
+		schemaRef.Title = enumName
+		schemaRef.Examples = []any{values[0]}
+		for _, v := range values {
+			schemaRef.Enum = append(schemaRef.Enum, string(v))
+		}
+		r.Map()[enumName] = schemaRef
+	}
+	return &huma.Schema{Ref: fmt.Sprintf("#/components/schemas/%s", enumName)}
+}