Add Documentation to Ci Lint API

doc/api/README.md

@@ -41,8 +41,10 @@ following locations:
 - [Sidekiq metrics](sidekiq_metrics.md)
 - [System Hooks](system_hooks.md)
 - [Tags](tags.md)
-- [Users](users.md)
 - [Todos](todos.md)
+- [Users](users.md)
+- [Validate the .gitlab-ci.yaml](ci_lint.md)
+
 ### Internal CI API

doc/api/ci_lint.md

+# Validate the .gitlab-ci.yaml
+
+Check whether your .gitlab-ci.yml file is valid.
+
+```
+POST ci/lint
+```
+
+| Attribute  | Type    | Required | Description |
+| ---------- | ------- | -------- | -------- |
+| `content`  | hash    | yes      | the .gitlab-ci.yaml content|
+
+```bash
+curl --request POST "https://gitlab.example.com/api/v3/ci/lint?content=YAML+Content"
+```
+
+Example response:
+
+* valid content
+
+```json
+{
+  "status": "valid",
+  "errors": []
+}
+```
+
+* invalid content
+
+```json
+{
+  "status": "invalid",
+  "errors": [
+    "variables config should be a hash of key value pairs"
+  ]
+}
+```
+
+* without the content attribute
+
+```json
+{
+  "error": "content is missing"
+}
+```

lib/api/lint.rb

@@ -7,14 +7,14 @@ module API
     namespace :ci do
       post '/lint' do
-        errors = Ci::GitlabCiYamlProcessor.validation_message(params[:content])
+        error = Ci::GitlabCiYamlProcessor.validation_message(params[:content])
         status 200
-        if errors.blank?
+        if error.blank?
           { status: 'valid', errors: [] }
         else
-          { status: 'invalid', errors: [errors] }
+          { status: 'invalid', errors: [error] }
         end
       end
     end