From b5914760c08b1dfaa05586d989d11d55cc80a2ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 19 Aug 2025 14:02:14 +0200 Subject: [PATCH] Adds links that point to the API contrib guidelines to repo docs (#5131) * Adds links that point to the API contrib guidelines to repo docs. * Apply suggestions from code review Co-authored-by: Quentin Pradet * Addresses feedback. * Apply suggestions from code review Co-authored-by: Quentin Pradet --------- Co-authored-by: Quentin Pradet --- README.md | 15 +++++++++++++++ docs/add-new-api.md | 3 +++ docs/doc-comments-guide.md | 4 +++- docs/schema-structure.md | 3 +++ 4 files changed, 24 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 004aa6e8af..bacd2b2f87 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,8 @@ The repository has the following structure: This JSON representation is formally defined by [a set of TypeScript definitions (a meta-model)](./compiler/src/model/metamodel.ts) that also explains the various properties and their values. +> [!TIP] +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to the [Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/). ## Prepare the environment @@ -74,6 +76,19 @@ $ make overlay-docs # The generated output can be found in ./output/openapi/ ``` +## Specification Viewer + +An interactive viewer for the Elasticsearch specification is available +[here](https://elastic.github.io/specification-viewer/). + +## Contributing + +See [CONTRIBUTING.md](./CONTRIBUTING.md) + +Refer to the +[Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/) +for more details about the API documentation guidelines. + ## Make Targets ``` diff --git a/docs/add-new-api.md b/docs/add-new-api.md index 5e082cab87..324f287510 100644 --- a/docs/add-new-api.md +++ b/docs/add-new-api.md @@ -5,6 +5,9 @@ in this repository, or we do have an endpoint definition in [`/specification/_js 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. +> [!TIP] +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to the [Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/). + ## How to add a new endpoint Add a new endpoint is straightforward, you only need to copy-paste the json rest-api-spec defintion diff --git a/docs/doc-comments-guide.md b/docs/doc-comments-guide.md index a8775a49fc..1f33aa1f4b 100644 --- a/docs/doc-comments-guide.md +++ b/docs/doc-comments-guide.md @@ -5,7 +5,7 @@ A specification is not only about formalizing data structures, it's also about e Documentation of the TypeScript specification is made using [JSDoc](https://jsdoc.app/) comments, i.e. multiline comments starting with `/**` above a type or field declaration. The first phrase is used as the mandatory operation summary in the OpenAPI document. -Refer to [API documentation guidelines](https://docs.elastic.dev/content-architecture/oas#summaries). +Refer to the [Elastic API docs contribution guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/guidelines) to learn more about how to create great documentation for your API. > [!NOTE] > You must add a period at the end of the phrase for it to parse correctly. The period will be properly omitted from the output OpenAPI document. @@ -76,6 +76,8 @@ GFM also has implementations in most languages, meaning that code generators wil ## Structuring a doc-comment +For guidelines of how to write great doc-comments, refer to the [Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/guidelines#write-descriptions) page. + ### Terseness **Doc comments are reference material**: they should be as succinct as possible while capturing all the necessary information to use the elements they're documenting. Remember that they will often show up in small IDE autocompletion popups! diff --git a/docs/schema-structure.md b/docs/schema-structure.md index 85183d8eac..1779361b5c 100644 --- a/docs/schema-structure.md +++ b/docs/schema-structure.md @@ -12,6 +12,9 @@ for describing APIs that can't be represented in the specification. Refer to the [documentation guide](doc-comments-guide.md) to add documentation to types and fields, and to the [modeling guide](modeling-guide.md) to learn how to model the different types. +> [!TIP] +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to the [Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/). + You can find the schema representing all APIs and types in the [output folder](output/schema/schema.json). The schema is structured as follows: