Description
🚀 Feature Proposal
- Add a way to manually add "summary" info for each operation.
- Update the OAS generator to populate the "summary" property from this data.
- Work with writing team to start populating the summary fields in this repo. Remove content from "description" fields if there's no additional value.
In OpenAPI specifications, each path and operation can have a summary field that provides a short description. Many documentation generators use this field in the full list of paths and in page headers. This field is optional but strongly recommended as the minimum necessary documentation.
Per https://spec.openapis.org/oas/latest#operation-object, the difference between the "summary" and "description" fields is as follows:
- summary (string): A short summary of what the operation does.
- description (string): A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
I would like to propose that we add support for it at the operation level at a minimum. The assumption is that though neither "summary" nor "description" are mandatory, for good docs "summary" is strongly recommended.
Per https://elastic.slack.com/archives/C0D8Y4ZJ9/p1696439430833169?thread_ts=1696362518.675159&cid=C0D8Y4ZJ9, there's been work done to add summaries for all Elasticsearch endpoints but since that content is currently just a duplication of the "description" field, it's not useful (and potentially redundant once we start publishing both the summary and the description in docsmobile). It's better to curate the content in the original specifications that try to generate it IMO.
Motivation
There are ongoing discussions about the best place to show the summary in docsmobile (https://github.com/elastic/api-reference-site/issues/61). Since it's likely to have prominent placement, we ought to start planning for this in the Elasticsearch specifications.
Example
Currently in https://github.com/elastic/elasticsearch-specification/blob/main/specification/async_search/delete/AsyncSearchDeleteRequest.ts we have content like this:
/**
* Deletes an async search by identifier.
* If the search is still running, the search request will be cancelled.
* Otherwise, the saved search results are deleted.
* If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the `cancel_task` cluster privilege.
* @rest_spec_name async_search.delete
... which yields output like this in https://raw.githubusercontent.com/elastic/elasticsearch-specification/openapi-converter/output/openapi/elasticsearch-serverless-openapi.json:
...
"delete": {
"tags": [
"async_search.delete"
],
"summary": "Deletes an async search by ID. If the search is still running, the search request will be cancelled. Otherwise, the saved search results are deleted.",
"description": "Deletes an async search by ID. If the search is still running, the search request will be cancelled. Otherwise, the saved search results are deleted.",
"externalDocs": {
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html"
},
"operationId": "async-search-delete",
"parameters": [
...
It would be preferable to have content like this:
...
"delete": {
"tags": [
"async_search.delete"
],
"summary": "Deletes an async search by ID.",
"description": "If the search is still running, the search request will be cancelled. Otherwise, the saved search results are deleted.",
"externalDocs": {
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html"
},
"operationId": "async-search-delete",
"parameters": [
...
Which could ideally be coded something like this:
/**
* If the search is still running, the search request will be cancelled.
* Otherwise, the saved search results are deleted.
* If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the `cancel_task` cluster privilege.
* @rest_spec_name async_search.delete
* @rest_spec_summary Deletes an async search by identifier.
NOTE: Ideally writers should be involved in creating the summaries (and just omit them from the OAS if they're not present in the ES spec) since it's likely not as simple as grabbing the first line of the description in all cases.