docs: Rewrite docs on writing API documentation.

This had gotten badly out of date, since it wasn't updated when we did
the big migration to the OpenAPI documentation system.

Fixes part of #12571.

tools/linter_lib/custom_check.py

@@ -588,6 +588,7 @@ css_rules = RuleList(
 
 prose_style_rules = cast(Rule, [
     {'pattern': r'[^\/\#\-"]([jJ]avascript)',  # exclude usage in hrefs/divs
+     'exclude': set(["docs/documentation/api.md"]),
      'description': "javascript should be spelled JavaScript"},
     {'pattern': r'''[^\/\-\."'\_\=\>]([gG]ithub)[^\.\-\_"\<]''',  # exclude usage in hrefs/divs
      'description': "github should be spelled GitHub"},