elastic / elastic/elasticsearch-specification
Add `@codegen_required` annotation to mark preferred location to serialize a parameter as required
- Dominant language
- TypeScript
- Stars
- 158
- Forks
- 136
- Avg merge
- 19h 48m
- Merged PRs (30d)
- 54
Description
In many places of the Elasticsearch API we allow serializing a parameter in multiple locations (path, query, body). The only way we can represent this within the spec is by marking all of these parameters as optional. However when generating a client there is only one place where a parameter "should" be serialized and therefore that parameter from a client perspective should be required, not optional.
I propose the annotation `@codegen_required` for this purpose. This is potentially what that would look like on the `ClearScrollRequest`:
```ts
import { RequestBase } from '@_types/Base'
import { Ids } from '@_types/common'
export interface Request extends RequestBase {
path_parts: {
scroll_id?: Ids
}
body: {
/**
* @codegen_required
*/
scroll_id?: Ids
}
}
```
which result in the following in the model (note `codegenRequired` in `body.properties.0`):
```json
{
"attachedBehaviors": [
"CommonQueryParameters"
],
"body": {
"kind": "properties",
"properties": [
{
"name": "scroll_id",
"required": false,
"codegenRequired": true,
"type": {
"kind": "instance_of",
"type": {
"name": "Ids",
"namespace": "_types"
}
}
}
]
},
"description": "Explicitly clears the search context for a scroll.",
"inherits": {
"type": {
"name": "RequestBase",
"namespace": "_types"
}
},
"kind": "request",
"name": {
"name": "Request",
"namespace": "_global.clear_scroll"
},
"path": [
{
"description": "A comma-separated list of scroll IDs to clear",
"name": "scroll_id",
"required": false,
"type": {
"kind": "instance_of",
"type": {
"name": "Ids",
"namespace": "_types"
}
}
}
],
"query": []
}
```
Contributor guide
Research direction
Start by tracing how the TypeScript request example for ClearScrollRequest is parsed into the generated model JSON. Verify how a @codegen_required annotation would be represented as codegenRequired while the specification remains optional, and confirm that client generation treats the preferred location as required.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100