openapi

func DefaultEndpointToolName ¶

func DefaultEndpointToolName(entityName, method, path string) string

DefaultEndpointToolName synthesises an MCP tool name from an entity + method + path triple. Used as a fallback when an Endpoint doesn't supply an explicit MCPName.

func EndpointInputSchema ¶ added in v0.3.3

func EndpointInputSchema(ep entity.Endpoint) map[string]any

EndpointInputSchema returns the JSON-Schema object describing an endpoint's request body. When ep.InputSchema is set it is converted via the same FieldsToSchema machinery the entity CRUD body uses; otherwise the historical {type:object} fallback is returned. This is the single source the OpenAPI requestBody and the generated MCP tool input schema both consume.

func EndpointOutputSchema ¶ added in v0.3.3

func EndpointOutputSchema(ep entity.Endpoint) map[string]any

EndpointOutputSchema returns the JSON-Schema object describing an endpoint's success (200) response body, falling back to {type:object} when ep.OutputSchema is unset.

func EntityEndpointPath ¶

func EntityEndpointPath(ent *entity.Entity, path string) string

EntityEndpointPath builds the absolute URL path for a custom Endpoint declared on an entity. Relative paths are joined under the entity's table; absolute paths pass through. ":id"-style params are converted to "{id}".

func EntityEndpointRoutePath ¶ added in v0.46.0

func EntityEndpointRoutePath(ent *entity.Entity, path, apiPrefix string) string

EntityEndpointRoutePath is EntityEndpointPath with the app's API prefix applied — the path the endpoint is actually mounted at.

A relative Endpoint.Path is documented as resolving against the entity's table path. Under WithAPIPrefix that table path is prefixed, so the endpoint must be too; without this an app using both ends up with its API split across two prefixes (CRUD at /api/licenses, the custom endpoint at /licenses/{id}/revoke) and nothing reports it.

An absolute path keeps bypassing the prefix. That is the documented escape hatch for mounting outside the entity's namespace.

The OpenAPI spec calls this too, not the unprefixed EntityEndpointPath. It used to use the latter, because the spec carried the prefix in its `servers` entry and its paths were prefix-relative by construction. Path keys are now absolute (see EntityOpenAPI), so the documented endpoint path has to be the mounted one — and routing through the same helper is what keeps the escape hatch behaving identically in both.

func EntityOpenAPI ¶

func EntityOpenAPI(registry entity.Registry, title, version string, basePath ...string) *openapi.Spec

EntityOpenAPI generates a full OpenAPI Spec from all registered entities. It produces:

• Schema components for each entity with typed fields
• CRUD paths (GET, POST, PUT, PATCH, DELETE) with request/response schemas
• List endpoint with pagination parameters
• Proper error response schemas

EntityOpenAPI builds the spec for every registered entity. An optional basePath (e.g. "/api", from AppConfig.APIPrefix) is baked into the per-path keys, so a documented path IS the path a client requests ("/api/posts"), and the single server entry stays "/".

This used to be the other way round: relative path keys ("/posts") plus a servers[0].url of "/api". That composes to the same URL and is legal OpenAPI, but it is the one form that misleads a reader who takes `paths` literally — and that reader is this framework's primary audience. The 2026-07-26 backend eval reproduced the confusion twice, in both its agent and its deterministic grader, and ranked fixing it as the highest-leverage change available. Repeating the prefix in `servers` as well would double it to /api/api/posts for any client that composes the two, so it does not.