Skip to content

Fix a few minor typos from contrib docs #4409

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −15
Draft

Fix a few minor typos from contrib docs #4409

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions docs/add-new-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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:
Expand All @@ -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`)
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand All @@ -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.
4 changes: 2 additions & 2 deletions docs/modeling-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`
Expand Down
4 changes: 2 additions & 2 deletions docs/specification-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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).
Expand Down
Loading