Snippets API doc fixes: content->code; visibility is required
This change fixes the description of Snippets API.
I have noticed that there are two inconsistencies between the documentation and API currently deployed on GitLab.com:
- Documentation claims that content fields is called
content
, while API says that it'scode
. -
visibility
field is marked as not required, while it is required in fact.
Here is an attempt to create a new snippet using API, starting from an empty request, adding required items one by one:
$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {}
> CDATA
{"error":"title is missing, file_name is missing, code is missing, code is empty, visibility is missing, visibility does not have a valid value"}
$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {"title": "test"}
> CDATA
{"error":"file_name is missing, code is missing, code is empty, visibility is missing, visibility does not have a valid value"}
$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {"title": "test", "file_name": "1.md"}
> CDATA
{"error":"code is missing, code is empty, visibility is missing, visibility does not have a valid value"}
$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {"title": "test", "file_name": "1.md", "code": "zz"}
> CDATA
{"error":"visibility is missing, visibility does not have a valid value"}
$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {"title": "test", "file_name": "1.md", "code": "zz", "visibility": "public"}
> CDATA
{"id":1859212,"title":"test","file_name":"1.md","description":null,"visibility":"public","author":{"id":1906296,"name":"Nikolay Samokhvalov","username":"NikolayS","state":"active","avatar_url":"https://assets.gitlab-static.net/uploads/-/system/user/avatar/1906296/avatar.png","web_url":"https://gitlab.com/NikolayS"},"updated_at":"2019-05-22T00:37:31.093Z","created_at":"2019-05-22T00:37:31.093Z","project_id":10031681,"web_url":"https://gitlab.com/NikolayS/test/snippets/1859212"}
From here, it's obvious that:
- content field is called
code
, notcontent
as the documentation states; -
visibility
is a required field.
This MR adjusts the documentation, in the sections related to creation and updating of snippets.
The corresponding sections in documentation:
Edited by Nikolay Samokhvalov