Description
Currently, the input specification does not contain any information about the body content type, we assume that is a plain JSON. In some cases, it should be ndjson, which we normally represent as an array of objects.
For example, here's the bulk API:
The only way for language generators for knowing this information is to read the contentType field of the Endpoint definition, which we are gathering from the rest-api-spec. For example:
"contentType": [
"application/x-ndjson"
]
🚀 Feature Proposal
Create a new js doc tag to track this information directly in the input spec.
Motivation
The rest-api-spec will not be there forever, and overtime we'll move most of the rest-api-spec information directly in the input spec. Furthermore I think strongly type languages will benefit from having this information easily accessible, but let's discuss more about it.
If we have a specific js doc tag for this we can instruct the compiler to throw if the body does not respect certain rules. For example, at the moment every ndjson API has the body defined as array.
Example
/**
* @rest_spec_name bulk
* @since 0.0.0
* @stability stable
+ * @content_type ndjson
*/
interface BulkRequest<TSource> extends RequestBase {
path_parts?: {
index?: IndexName
type?: Type
}
query_parameters?: {
pipeline?: string
refresh?: Refresh
routing?: Routing
_source?: boolean
_source_excludes?: Fields
_source_includes?: Fields
timeout?: Time
type_query_string?: string
wait_for_active_shards?: WaitForActiveShards
require_alias?: boolean
}
body?: Array<BulkOperationContainer | TSource>
}