Customize generated OpenAPI schemas

[edlundin]

This lets developers add OpenAPI details on types.

For Go, fields can use an openapi struct tag:

  //encore:enum
  type OrderStatus string

  const (
      Pending   OrderStatus = "pending"
      Paid      OrderStatus = "paid"
      Cancelled OrderStatus = "cancelled"
  )

  type CreateOrderParams struct {
      CustomerEmail string      `json:"customer_email" openapi:"format=email;example=customer@example.com"`
      Quantity      int         `json:"quantity" openapi:"minimum=1;maximum=100;default=1;example=2"`
      Status        OrderStatus `json:"status" openapi:"example=pending"`
  }

For TypeScript, the same metadata can be added with @openapi comments:

  interface CreateOrderParams {
    /** @openapi format=email;example=customer@example.com */
    customerEmail: string;

    /** @openapi enum=pending|paid|cancelled;example=pending */
    status: string;
  }

Supported OpenAPI metadata

Tag	Description	Example
example	Sets the OpenAPI example value.	example=customer@example.com
default	Documents the default value.	default=1
format	Sets the OpenAPI format.	format=email
deprecated	Marks a field as deprecated.	deprecated=true
enum	Sets allowed values inline. In Go, you can use a typed enum with //encore:enum when the values belong to a named type.	enum=pending|paid|cancelled
minimum, min	Sets the minimum numeric value.	minimum=1
maximum, max	Sets the maximum numeric value.	maximum=100
minLength	Sets the minimum string length.	minLength=2
maxLength	Sets the maximum string length.	maxLength=280
pattern	Sets a regex pattern for strings.	pattern=^[0-9]{5}$