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

@@ -8,9 +8,9 @@ Get all labels for a given project.
 GET /projects/:id/labels
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of the project |
+| Attribute | Type    | Required | Description           |
+| --------- | ------- | -------- | --------------------- |
+| `id`      | integer | yes      | The ID of the project |
 
 ```bash
 curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/1/labels
@@ -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"
    }
 ]
 ```
@@ -66,11 +74,12 @@ and 409 if the label already exists.
 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 |
+| 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
 }
 ```
 
@@ -97,10 +107,10 @@ In case of an error, an additional error message is returned.
 DELETE /projects/:id/labels
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes | The ID of the project |
-| `name`    | string  | yes | The name of the label |
+| Attribute | Type    | Required | Description           |
+| --------- | ------- | -------- | --------------------- |
+| `id`      | integer | yes      | The ID of the project |
+| `name`    | string  | yes      | The name of the label |
 
 ```bash
 curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug"
@@ -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,
@@ -133,15 +144,16 @@ In case of an error, an additional error message is returned.
 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 |
+| 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

@@ -17,17 +17,18 @@ module API
       # Creates a new label
       #
       # Parameters:
-      #   id    (required) - The ID of a project
-      #   name  (required) - The name of the label to be deleted
-      #   color (required) - Color of the label given in 6-digit hex
-      #                      notation with leading '#' sign (e.g. #FFAABB)
+      #   id    (required)       - The ID of a project
+      #   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
@@ -62,11 +63,12 @@ module API
       # Updates an existing label. At least one optional parameter is required.
       #
       # Parameters:
-      #   id        (required) - The ID of a project
-      #   name      (required) - The name of the label to be deleted
-      #   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)
+      #   id        (required)   - The ID of a project
+      #   name      (required)   - The name of the label to be deleted
+      #   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',