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.

Distinct routes keep distinct names: "/" becomes "_", a hyphen stays a hyphen (MCP tool names allow it), and a {param} segment becomes "-param-", so "/feed/items" and "/feed-items", or "/items/{id}" and "/items/id", never fold together. Only the method is case-folded; entity and path spelling is preserved, since routes are case-sensitive.

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.

A versioned entity (App.GroupEntity) carries its group prefix as Version, and the router mounts that prefix absolutely, so the API prefix is not applied on top of it: "/api/v1/posts/revoke", never "/api/api/v1/posts/revoke".

func EntityOpenAPI ¶

func EntityOpenAPI(registry entity.Registry, title, version string, crudMounted func(*entity.Entity) bool, 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 most valuable 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.

crudMounted reports whether an entity's auto-CRUD routes were actually registered. The app passes its route predicate (DB attached AND Exposure.CRUD), so the spec cannot advertise CRUD paths registration never mounted — the Exposure flag alone misses the no-DB case (#266). nil falls back to the Exposure-only check. Declared custom Endpoints are documented either way; App mounts those outside its CRUD branch.