From b63d20a1064c20204defd1d78af97893eb2b3fc8 Mon Sep 17 00:00:00 2001
From: Katarzyna Kobierska <kkobierska@gmail.com>
Date: Wed, 31 Aug 2016 11:16:25 +0200
Subject: [PATCH] Add Documentation to Ci Lint API

---
 doc/api/README.md  |  4 +++-
 doc/api/ci_lint.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 lib/api/lint.rb    |  6 +++---
 3 files changed, 51 insertions(+), 4 deletions(-)
 create mode 100644 doc/api/ci_lint.md

diff --git a/doc/api/README.md b/doc/api/README.md
index 96d94e08487..67ec502346e 100644
--- a/doc/api/README.md
+++ b/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
 
diff --git a/doc/api/ci_lint.md b/doc/api/ci_lint.md
new file mode 100644
index 00000000000..2b169176dd6
--- /dev/null
+++ b/doc/api/ci_lint.md
@@ -0,0 +1,45 @@
+# 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"
+}
+```
diff --git a/lib/api/lint.rb b/lib/api/lint.rb
index ec9c8c710e4..0af132803ba 100644
--- a/lib/api/lint.rb
+++ b/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