Clarify graph collection removal, add missing collection/View response descriptions, improve OpenAPI rendering

[Simran-B]

Description

Some of the collection/View/Gharial endpoint descriptions are incomplete/incorrect. Originally reported by Jakub.

Most of the endpoints seem to return the full collection/View metadata (sometimes with additional properties). To properly document this, we need a lot of duplication. We don't currently have a way to de-duplicate structural descriptions, and there would definitely be downsides to it as well. Various additions, improvements, and corrections are in this PR.

Should we document the HTTP responses that you get if you use async jobs? It is always status code 202 (Accepted) -> Not for the time being at least. This would seemingly affect ALL endpoints!

Changes to OpenAPI handling:

• enum and default are not rendered in the docs -> Now they are, the former at the end of the description (Possible values: ...), the latter next to the parameter/property type
• Fix required indicator (* after name) for nested properties
• Fix internal links for online docs as well as Swagger UI (api-docs.json)
• Hide anchors/fragment identifiers of polymorphic endpoints, e.g. POST /_api/view#searchalias -> POST /_api/view)
• Display descriptions for HTTP response status codes, e.g. Created next to 201
• Show content type for responses too (application/json)

Examples:

• links has a cross-reference, primarySortCompression shows its default value and the Possible values in the description, the Responses show status descriptions (Created, Bad Request, Conflict) and a content type https://deploy-preview-467--docs-hugo.netlify.app/stable/develop/http-api/views/arangosearch-views/
• keyOptions* is required (hence the asterisk) but some of its sub-properties are optional https://deploy-preview-467--docs-hugo.netlify.app/stable/develop/http-api/collections/#get-the-properties-of-a-collection_res_200_keyOptions

Upstream PRs

• 3.10:
• 3.11:
• 3.12:

[arangodb-docs-automation[bot]]

Deploy Preview Available Via
https://deploy-preview-467--docs-hugo.netlify.app