API documentation

← API documentation

Ashterix

docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api

en/docs/api/rest-bundle/documentation.md new file +90 −0

API documentation

Each REST entry point publishes two documents for each API version. They contain only the methods of that entry point's group and version, and its URL.

Request Response
GET /rest An OpenAPI 3.1 document
GET /rest/postman A Postman collection
GET /rest/v2, GET /rest/v2/postman The same for API version v2
GET /internal, … The same for an API group entry point

If protected_doc: true is set in the JsonRpcBundle settings, these requests require the group's token; see Security.

What goes into OpenAPI

Element Source
info.title, info.description ufo_json_rpc.docs.project_name, project_description
info.version the requested API version
info.x-versions all versions of the group
servers[0].url the document URL from the current request
servers[0].x-ufo envelope REST (RFC 9110, 9457)/UFO-REST-<package version>, environment, links to specifications
paths.<path>.<method> one operation per REST route
operationId the RPC method name (catalog.item)
summary, description the method title and description (see below)
tags the RPC procedure alias
deprecated @deprecated or #[\Deprecated] on the method
parameters path variables (in: path, required) with the method parameter's schema
requestBody the other parameters as a JSON object: required flags, default values, descriptions, types, enums and DTO references
responses.200 the schema of the result type
responses.<status> error statuses from @throws
components.schemas DTOs and enums used by the operations 
/**
 * Returns an item by id
 * @param int $id Item identifier
 * @throws RpcDataNotFoundException
 */
#[Route('/items/{id}', name: 'item', methods: ['GET'])]
public function item(int $id): ItemDto

Here @throws RpcDataNotFoundException adds a 404 response to the operation: each exception from @throws is converted according to the error table, one response per status. @throws \Throwable is documented as RestApplicationException (400).

Path variables are documented with their parameter's schema since 1.3; before that, as string.

Postman collection

  • The collection is named REST: <project_name>, with a [group] suffix for a group other than general (since 1.2).
  • Variables base_url (the host of the current request) and apiToken.
  • Requests are grouped into folders by RPC procedure; each is named by its path.
  • Each request has the route's HTTP method, a URL with Postman path variables (/items/:id), the Content-Type and token headers, and a raw JSON body with sample parameter values, except path variables.

Translating titles and descriptions

Since version 1.3, requires JsonRpcBundle 10.4.

Method titles and descriptions come from the JsonRpcBundle translations, the same as for the RPC documentation:

translations/rpc.<locale>.yaml          # base, for all groups
translations/rpc/<group>.<locale>.yaml  # override for an API group

# translations/rpc.en.yaml
catalog.item:
    title: Item
    description: Returns an item by id

Extension directories are added via ufo_json_rpc.translations.paths. The language is chosen from Accept-Language among the languages that have translations (uk-UA gives uk); the response gets Content-Language and Vary: Accept-Language.

OpenAPI field Value
summary the translated title; without a title, the description; without both, the RPC method name
description the translated description, if there is a title

Postman collection requests get the translated description.

Limitations

  • Documents are generated on every request; there is no ETag caching as in the RPC documentation.
  • For GET methods parameters are documented as a request body (requestBody in OpenAPI, raw JSON in Postman), although the bundle also accepts them from the query.
  • For a route with several HTTP methods only the first one is documented.

See Open issues.