API Documentation

Encore parses doc comments from your Go source code and surfaces them in the Service Catalog, generated API clients, and OpenAPI specs. This means your documentation stays in your code and is always up to date.

Services

A service's documentation comes from the Go package doc comment — the comment block immediately before the package declaration.

// Payments handles payment processing, billing,
// and subscription management.
package payments

Service docs appear in the Service Catalog and in generated API clients.

Service structs

If you use a service struct, the doc comment on the struct type is also extracted.

// PaymentService manages payment processing state and dependencies.
//
//encore:service
type PaymentService struct {
    // ...
}

API endpoints

Add a comment block above the //encore:api directive to document an endpoint.

// Charge charges the given payment method.
// It is idempotent; calling it multiple times
// with the same idempotency key has no additional effect.
//
//encore:api auth
func Charge(ctx context.Context, params *ChargeParams) (*ChargeResponse, error) {
    // ...
}

In the OpenAPI spec, the first line becomes the summary and the remaining lines become the description.

Auth handlers

// AuthenticateRequest validates the API key provided in the Authorization header
// and returns the authenticated user's information.
//
//encore:authhandler
func AuthenticateRequest(ctx context.Context, token string) (auth.UID, *UserData, error) {
    // ...
}

Middleware

// LogRequests logs all incoming requests and their duration.
//
//encore:middleware target=all
func LogRequests(req middleware.Request, next middleware.Next) middleware.Response {
    // ...
}

Types

Document types with a comment above the type declaration.

// ChargeParams defines the parameters for the Charge endpoint.
type ChargeParams struct {
    // PaymentMethodID is the identifier of the payment method to charge.
    PaymentMethodID string

    // Amount is the amount to charge, in the smallest currency unit (e.g. cents).
    Amount int

    Currency string // ISO 4217 currency code
}

Both the type-level and field-level comments are surfaced in generated clients and OpenAPI schemas.

Infrastructure resources

Doc comments are also supported on infrastructure resource declarations.

// TransactionDB stores payment transactions and related records.
var TransactionDB = sqldb.NewDatabase("transactions", sqldb.DatabaseConfig{
    Migrations: "./migrations",
})

// PaymentEvents publishes events when payment states change.
var PaymentEvents = pubsub.NewTopic[*PaymentEvent]("payment-events", pubsub.TopicConfig{
    DeliveryGuarantee: pubsub.AtLeastOnce,
})

// ProcessPaymentEvent handles incoming payment events.
var _ = pubsub.NewSubscription(PaymentEvents, "process-payment", pubsub.SubscriptionConfig[*PaymentEvent]{
    Handler: handlePaymentEvent,
})

// DailySettlement runs the settlement process every day at midnight.
var DailySettlement = cron.NewJob("daily-settlement", cron.JobConfig{
    Every:    24 * cron.Hour,
    Endpoint: Settle,
})

// PaymentCache caches frequently accessed payment records.
var PaymentCache = cache.NewCluster("payment-cache", cache.ClusterConfig{
    EvictionPolicy: cache.AllKeysLRU,
})

// PaymentByID caches payments by their unique identifier.
var PaymentByID = cache.NewStringKeyspace[Payment](PaymentCache, cache.KeyspaceConfig{
    KeyPattern: "payment/:id",
})

// Receipts stores generated receipt PDFs.
var Receipts = objects.NewBucket("receipts", objects.BucketConfig{})

// ChargeAmount tracks the total amount charged per currency.
var ChargeAmount = metrics.NewCounterGroup[ChargeLabels, uint64]("charge_amount", metrics.CounterConfig{})

type ChargeLabels struct {
    // Currency is the ISO 4217 currency code.
    Currency string
}

These docs appear in the Service Catalog and are available through the MCP server for AI-assisted development.

Where docs appear