diff --git a/docs/add-new-api.md b/docs/add-new-api.md index bdea31de22..da5fcf20f3 100644 --- a/docs/add-new-api.md +++ b/docs/add-new-api.md @@ -3,11 +3,11 @@ It might happen that a new API in Elasticsearch is not yet defined in this repository, or we do have an endpoint definition in [`/specification/_json_spec`](../specification/_json_spec) but we don't have a type definition for it. -In this document you will see how to add a new endpopint and how to add a new endpoint definition. +In this document you will see how to add a new endpoint and how to add a new endpoint definition. ## How to add a new endpoint -Add a new endpoint is straightforward, you only need to copy-paste the json rest-api-spec defintion +Add a new endpoint is straightforward, you only need to copy-paste the json rest-api-spec definition from the Elasticsearch repository inside [`/specification/_json_spec`](../specification/_json_spec) and you are good to go. @@ -17,10 +17,10 @@ or [here](https://github.com/elastic/elasticsearch/tree/7.x/x-pack/plugin/src/te ## How to add the definition of an endpoint Once you have added a new endpoint definition, the next step is to add its type definition. -First of all, you should find the most approariate place inside [`/specification`](../specification) +First of all, you should find the most appropriate place inside [`/specification`](../specification) where to put the new definition. The content of [`/specification`](../specification) -tryied to mimic the Elasticsearch online documentation, so you can use it as inspiration. -For example, the index document defintion can be found in [`/specification/_global/index`](../specification/_global/index). +tried to mimic the Elasticsearch online documentation, so you can use it as inspiration. +For example, the index document definition can be found in [`/specification/_global/index`](../specification/_global/index). Once you have found the best place for the new definition, you should create a new file for it. The filename should be the same of the type definition you are writing, for example: @@ -40,16 +40,16 @@ you can define it in the same file where it's used, unless is a commonly used ty ### Add the endpoint request definition -Request definitions are slighly different from other definitions. +Request definitions are slightly different from other definitions. It is required that the request definition is named `Request`. -A request definition is an interface and should contains three top level keys: +A request definition is an interface and should contain these top level keys: - `urls`: the URL paths templates and allowed HTTP methods - `path_parts`: the path parameters (eg: `indices`, `id`...) - `query_parameters`: the query parameters (eg: `timeout`, `pipeline`...) - `body`: the body parameters (eg: `query` or user defined entities) -Furthermore, every request definition **must** contain three JS Doc tags: +Furthermore, every request definition **must** contain these JS Doc tags: - `@rest_spec_name`: the API name (eg: `search`, `indices.create`...). - `@availability` Which flavor of Elasticsearch is this API available for? (eg `stack` or `serverless`) @@ -130,7 +130,7 @@ class Response { ``` As you can see, for responses there are no custom top level keys, as the -response definition represents the body of a succesful response. +response definition represents the body of a successful response. #### Generics @@ -172,7 +172,7 @@ class Response { Add an `examples` folder and `request` and `xxx_response` subfolders (where `xxx` is the relevant response code). The file names within these folders should be unique (for example,`DownsampleRequestExample1.yaml` not `RequestExample1.yaml`). These examples are for use in the API documentation and must adhere to the [OpenAPI 3.0 Example object specification](https://spec.openapis.org/oas/v3.0.3#example-object). They must have a `value` field that contains the request or response body. -If there are multiple examples for the endpoint, they must each have a brief `summary` field, which is used as the label for the example. You can also optionaly provide an explanation in a `description` field. +If there are multiple examples for the endpoint, they must each have a brief `summary` field, which is used as the label for the example. You can also optionally provide an explanation in a `description` field. For example: @@ -196,5 +196,5 @@ value: |- ``` NOTE: A good example covers a very common use case or demonstrates a more complex but critical use case. -It involves realistic data sets ( rather than generic "hello world" values). +It involves realistic data sets (rather than generic "hello world" values). If it requires detailed setup or explanations, however, it is more appropriate for coverage in longer-form narrative documentation. diff --git a/docs/modeling-guide.md b/docs/modeling-guide.md index 32eef7f219..b8d9cfd723 100644 --- a/docs/modeling-guide.md +++ b/docs/modeling-guide.md @@ -148,7 +148,7 @@ property: UserDefinedValue ### Numbers -The numeric type in TypeScript is `number`, but given that this specification targets mutliple languages, +The numeric type in TypeScript is `number`, but given that this specification targets multiple languages, it offers a bunch of aliases that represent the type that should be used if the language supports it: ```ts @@ -502,7 +502,7 @@ Code generators should track the `es_quirk` they implement and fail if a new unh ### Additional information -If needed, you can specify additional information on each type with the approariate JSDoc tag. +If needed, you can specify additional information on each type with the appropriate JSDoc tag. Following you can find a list of the supported tags: #### `@availability` diff --git a/docs/specification-structure.md b/docs/specification-structure.md index 9dc7cdf22d..fbf86008ce 100644 --- a/docs/specification-structure.md +++ b/docs/specification-structure.md @@ -1,7 +1,7 @@ # Specification structure The [`/specification`](../specification) folders follows a set of rules to -keep the defintion easy to access and contribute, while maintaing +keep the definition easy to access and contribute, while maintaining the generated schema consistent and useful for language generators. ## Rules @@ -29,7 +29,7 @@ end with `Request` or `Response`. ### Request and Response definitions -Request and Reponse definitions should be placed by structly following +Request and Response definitions should be placed by strictly following the rest-api-spec structure. For example, the request and response definition for `indices.put_mapping` should go in [`/specification/indices/put_mapping`](../specification/indices/put_mapping).