Description
🚀 Feature Proposal
Hard-coded documentation URLs require maintenance across the specification source files when our URLs change. In Kibana, we use a documentation link service that maps keywords to URLs, so that we can use the keywords within the apps and maintain the full URLs in a single place. A similar keyword<->URL mapping list and support for keywords in the docUrl field and @doc_url comments would be helpful.
In the long run, we might want to move to using primed doc queries instead of linking to specific pages. That could be accomplished within the keyword mapping file too but in the future we might want to consider supporting primed search terms in the docUrl field.
Motivation
Hardcoded URLs in the spec are subject to link rot and, in the current system, frequent build failures as content moves around.
Example
Instead of something like this:
"docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html",
or
/**
* Boolean) If true, the request is real-time as opposed to near-real-time.
* @doc_url https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html#realtime
*/
... we would ideally have a simple unique keyword (or in the long term, maybe search terms) that is resolved into the appropriate URL as part of the client/docs generation.