Document the snippet clone URLs and the public snippet import fields

What does this MR do and why?

ssh_url_to_repo and http_url_to_repo are exposed by API::Entities::BasicSnippet, which every snippet entity on both of these pages inherits from, and they were documented unevenly: present in three of the five response attribute tables on doc/api/snippets.md and in two of its eight example snippets, and absent from all four tables and all four examples on doc/api/project_snippets.md.

imported and imported_from were documented everywhere except the "List all public snippets" section, whose table and both example snippets predate them.

Two pages in one merge request because it is the same two fields on the same entity chain: PersonalSnippet < Snippet < BasicSnippet and ProjectSnippet < Snippet < BasicSnippet. Splitting it would put the same question in front of the same reviewer twice.

What changed:

  • doc/api/snippets.md: ssh_url_to_repo and http_url_to_repo added to the tables for "List all snippets for current user", "List all public snippets" and "List all snippets"; imported and imported_from added to the "List all public snippets" table. Five example snippets gained the clone URLs and the two public ones gained the import fields.
  • doc/api/project_snippets.md: both fields added to all four response attribute tables and all four example snippets.

Both are described as returned only if the snippet repository exists, which is their condition: if: ->(snippet) { snippet.repository_exists? }.

Two deliberate omissions, so they do not read as oversights.

The three snippets in the "List all snippets" example carry "file_name": "" and "files": [], so they are examples of snippets with no content. I left the clone URLs off those rather than assert a repository the example does not show; the table for that section lists both fields, which is where a reader looks for what may be returned.

I also corrected one typo inside an object I was already editing: in "List all public snippets", the second snippet has id 48 and its raw_url pointed at snippet 49.

I found this while adding the same four fields to the Go API client, in gitlab-org/api/client-go!3053 (merged).

MR acceptance checklist

This change is documentation only. No endpoint, parameter or behaviour changes.

I parsed every JSON block on both pages after editing. All fourteen still parse. On doc/api/snippets.md the two blocks that are request payloads and the user agent detail block are untouched, as is the "List all snippets" example for the reason above; on doc/api/project_snippets.md every snippet object now carries all four fields and the user agent detail block is untouched.

Merge request reports

Loading
Loading