Description
We received feedback that the description in https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-search#operation-search-body-application-json-retriever-search_after is poor:
search_after array[number | string | boolean | null]
A field value.
That documentation is derived from https://github.com/elastic/elasticsearch-specification/blob/main/specification/_global/search/SearchRequest.ts:
/**
* Used to retrieve the next page of hits using a set of sort values from the previous page.
*/
search_after?: SortResults
I believe that when you use OpenAPI 3.0, however, you cannot have descriptions that are peers to re-used schemas, which is why the OpenAPI document is missing that detail:
"search_after": {
"$ref": "#/components/schemas/_types:SortResults"
}
Instead, it contains only what appears in the SortResults object, which is defined in http://github.com/elastic/elasticsearch-specification/blob/main/specification/_types/sort.ts
export type SortResults = FieldValue[]
It will need to be investigated whether there's a more meaningful description that can be added (likely in the sort.ts file that is applicable to all the places where that object is re-used. Then verify that it gets properly percolated into the OpenAPI output.