api - expose label description

CHANGELOG

@@ -4,6 +4,7 @@ v 8.7.0 (unreleased)
   - Preserve time notes/comments have been updated at when moving issue
   - Make HTTP(s) label consistent on clone bar (Stan Hu)
   - Fix avatar stretching by providing a cropping feature
+  - Expose label description in API (Mariusz Jachimowicz)
 
 v 8.6.1
   - Add option to reload the schema before restoring a database backup. !2807

doc/api/labels.md

@@ -9,7 +9,7 @@ GET /projects/:id/labels
 ```
 
 | Attribute | Type    | Required | Description           |
-| --------- | ---- | -------- | ----------- |
+| --------- | ------- | -------- | --------------------- |
 | `id`      | integer | yes      | The ID of the project |
 
 ```bash
@@ -22,35 +22,43 @@ Example response:
 [
    {
       "name" : "bug",
-      "color" : "#d9534f"
+      "color" : "#d9534f",
+      "description": "Bug reported by user"
    },
    {
       "color" : "#d9534f",
-      "name" : "confirmed"
+      "name" : "confirmed",
+      "description": "Confirmed issue"
    },
    {
       "name" : "critical",
-      "color" : "#d9534f"
+      "color" : "#d9534f",
+      "description": "Criticalissue. Need fix ASAP"
    },
    {
       "color" : "#428bca",
-      "name" : "discussion"
+      "name" : "discussion",
+      "description": "Issue that needs further discussion"
    },
    {
       "name" : "documentation",
-      "color" : "#f0ad4e"
+      "color" : "#f0ad4e",
+      "description": "Issue about documentation"
    },
    {
       "color" : "#5cb85c",
-      "name" : "enhancement"
+      "name" : "enhancement",
+      "description": "Enhancement proposal"
    },
    {
       "color" : "#428bca",
-      "name" : "suggestion"
+      "name" : "suggestion",
+      "description": "Suggestion"
    },
    {
       "color" : "#f0ad4e",
-      "name" : "support"
+      "name" : "support",
+      "description": "Support issue"
    }
 ]
 ```
@@ -67,10 +75,11 @@ POST /projects/:id/labels
 ```
 
 | Attribute     | Type    | Required | Description                  |
-| --------- | ---- | -------- | ----------- |
+| ------------- | ------- | -------- | ---------------------------- |
 | `id`          | integer | yes      | The ID of the project        |
 | `name`        | string  | yes      | The name of the label        |
 | `color`       | string  | yes      | The color of the label in 6-digit hex notation with leading `#` sign |
+| `description` | string  | no       | The description of the label |
 
 ```bash
 curl --data "name=feature&color=#5843AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
@@ -81,7 +90,8 @@ Example response:
 ```json
 {
    "name" : "feature",
-   "color" : "#5843AD"
+   "color" : "#5843AD",
+   "description":null
 }
 ```
 
@@ -98,7 +108,7 @@ DELETE /projects/:id/labels
 ```
 
 | Attribute | Type    | Required | Description           |
-| --------- | ---- | -------- | ----------- |
+| --------- | ------- | -------- | --------------------- |
 | `id`      | integer | yes      | The ID of the project |
 | `name`    | string  | yes      | The name of the label |
 
@@ -112,6 +122,7 @@ Example response:
 {
    "title" : "feature",
    "color" : "#5843AD",
+   "description": "New feature proposal",
    "updated_at" : "2015-11-03T21:22:30.737Z",
    "template" : false,
    "project_id" : 1,
@@ -134,14 +145,15 @@ PUT /projects/:id/labels
 ```
 
 | Attribute       | Type    | Required                          | Description                      |
-| --------- | ---- | -------- | ----------- |
+| --------------- | ------- | --------------------------------- | -------------------------------  |
 | `id`            | integer | yes                               | The ID of the project            |
 | `name`          | string  | yes                               | The name of the existing label   |
 | `new_name`      | string  | yes if `color` if not provided    | The new name of the label        |
 | `color`         | string  | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign |
+| `description`   | string  | no                                | The new description of the label |
 
 ```bash
-curl -X PUT --data "name=documentation&new_name=docs&color=#8E44AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
+curl -X PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
 ```
 
 Example response:
@@ -149,6 +161,7 @@ Example response:
 ```json
 {
    "color" : "#8E44AD",
-   "name" : "docs"
+   "name" : "docs",
+   "description": "Documentation"
 }
 ```

lib/api/entities.rb

@@ -292,7 +292,7 @@ module API
     end
 
     class Label < Grape::Entity
-      expose :name, :color
+      expose :name, :color, :description
     end
 
     class Compare < Grape::Entity

lib/api/labels.rb

@@ -18,16 +18,17 @@ module API
       #
       # Parameters:
       #   id    (required)       - The ID of a project
-      #   name  (required) - The name of the label to be deleted
+      #   name  (required)       - The name of the label to be created
       #   color (required)       - Color of the label given in 6-digit hex
       #                            notation with leading '#' sign (e.g. #FFAABB)
+      #   description (optional) - The description of label to be created
       # Example Request:
       #   POST /projects/:id/labels
       post ':id/labels' do
         authorize! :admin_label, user_project
         required_attributes! [:name, :color]
 
-        attrs = attributes_for_keys [:name, :color]
+        attrs = attributes_for_keys [:name, :color, :description]
         label = user_project.find_label(attrs[:name])
 
         conflict!('Label already exists') if label
@@ -67,6 +68,7 @@ module API
       #   new_name  (optional)   - The new name of the label
       #   color     (optional)   - Color of the label given in 6-digit hex
       #                            notation with leading '#' sign (e.g. #FFAABB)
+      #   description (optional) - The description of label to be created
       # Example Request:
       #   PUT /projects/:id/labels
       put ':id/labels' do
@@ -76,7 +78,7 @@ module API
         label = user_project.find_label(params[:name])
         not_found!('Label not found') unless label
 
-        attrs = attributes_for_keys [:new_name, :color]
+        attrs = attributes_for_keys [:new_name, :color, :description]
 
         if attrs.empty?
           render_api_error!('Required parameters "new_name" or "color" ' \

spec/requests/api/labels_spec.rb

@@ -23,13 +23,25 @@ describe API::API, api: true  do
   end
 
   describe 'POST /projects/:id/labels' do
-    it 'should return created label' do
+    it 'should return created label when all params' do
+      post api("/projects/#{project.id}/labels", user),
+           name: 'Foo',
+           color: '#FFAABB',
+           description: 'test'
+      expect(response.status).to eq(201)
+      expect(json_response['name']).to eq('Foo')
+      expect(json_response['color']).to eq('#FFAABB')
+      expect(json_response['description']).to eq('test')
+    end
+
+    it 'should return created label when only required params' do
       post api("/projects/#{project.id}/labels", user),
            name: 'Foo',
            color: '#FFAABB'
       expect(response.status).to eq(201)
       expect(json_response['name']).to eq('Foo')
       expect(json_response['color']).to eq('#FFAABB')
+      expect(json_response['description']).to be_nil
     end
 
     it 'should return a 400 bad request if name not given' do
@@ -94,14 +106,16 @@ describe API::API, api: true  do
   end
 
   describe 'PUT /projects/:id/labels' do
-    it 'should return 200 if name and colors are changed' do
+    it 'should return 200 if name and colors and description are changed' do
       put api("/projects/#{project.id}/labels", user),
           name: 'label1',
           new_name: 'New Label',
-          color: '#FFFFFF'
+          color: '#FFFFFF',
+          description: 'test'
       expect(response.status).to eq(200)
       expect(json_response['name']).to eq('New Label')
       expect(json_response['color']).to eq('#FFFFFF')
+      expect(json_response['description']).to eq('test')
     end
 
     it 'should return 200 if name is changed' do
@@ -122,6 +136,15 @@ describe API::API, api: true  do
       expect(json_response['color']).to eq('#FFFFFF')
     end
 
+    it 'should return 200 if description is changed' do
+      put api("/projects/#{project.id}/labels", user),
+          name: 'label1',
+          description: 'test'
+      expect(response.status).to eq(200)
+      expect(json_response['name']).to eq(label1.name)
+      expect(json_response['description']).to eq('test')
+    end
+
     it 'should return 404 if label does not exist' do
       put api("/projects/#{project.id}/labels", user),
           name: 'label2',