Adds sorting to deployments API

Adds sorting to deployments API through the `order_by` and sort
`fields`.

changelogs/unreleased/41118-add-sorting-to-deployments-api.yml

+---
+title: Adds sorting to deployments API
+merge_request: !16396
+author: Jacopo Beschi @jacopo-beschi
+type: added

doc/api/deployments.md

@@ -11,6 +11,8 @@ GET /projects/:id/deployments
 | Attribute | Type    | Required | Description         |
 |-----------|---------|----------|---------------------|
 | `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `order_by`| string  | no       | Return deployments ordered by `id` or `iid` or `created_at` or `ref` fields. Default is `id` |
+| `sort`    | string  | no       | Return deployments sorted in `asc` or `desc` order. Default is `asc` |
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/deployments"

lib/api/deployments.rb

@@ -15,11 +15,13 @@ module API
       end
       params do
         use :pagination
+        optional :order_by, type: String, values: %w[id iid created_at ref], default: 'id', desc: 'Return deployments ordered by `id` or `iid` or `created_at` or `ref`'
+        optional :sort, type: String, values: %w[asc desc], default: 'asc', desc: 'Sort by asc (ascending) or desc (descending)'
       end
       get ':id/deployments' do
         authorize! :read_deployment, user_project
-        present paginate(user_project.deployments), with: Entities::Deployment
+        present paginate(user_project.deployments.order(params[:order_by] => params[:sort])), with: Entities::Deployment
       end
       desc 'Gets a specific deployment' do

spec/requests/api/deployments_spec.rb

@@ -3,24 +3,65 @@ require 'spec_helper'
 describe API::Deployments do
   let(:user)        { create(:user) }
   let(:non_member)  { create(:user) }
-  let(:project)     { deployment.environment.project }
-  let!(:deployment) { create(:deployment) }
   before do
     project.add_master(user)
   end
   describe 'GET /projects/:id/deployments' do
+    let(:project) { create(:project) }
+    let!(:deployment_1) { create(:deployment, project: project, iid: 11, ref: 'master', created_at: Time.now) }
+    let!(:deployment_2) { create(:deployment, project: project, iid: 12, ref: 'feature', created_at: 1.day.ago) }
+    let!(:deployment_3) { create(:deployment, project: project, iid: 8, ref: 'feature', created_at: 2.days.ago) }
+
     context 'as member of the project' do
-      it 'returns projects deployments' do
+      it 'returns projects deployments sorted by id asc' do
         get api("/projects/#{project.id}/deployments", user)
         expect(response).to have_gitlab_http_status(200)
         expect(response).to include_pagination_headers
         expect(json_response).to be_an Array
-        expect(json_response.size).to eq(1)
-        expect(json_response.first['iid']).to eq(deployment.iid)
+        expect(json_response.size).to eq(3)
+        expect(json_response.first['iid']).to eq(deployment_1.iid)
         expect(json_response.first['sha']).to match /\A\h{40}\z/
+        expect(json_response.second['iid']).to eq(deployment_2.iid)
+        expect(json_response.last['iid']).to eq(deployment_3.iid)
+      end
+
+      describe 'ordering' do
+        using RSpec::Parameterized::TableSyntax
+
+        let(:order_by) { nil }
+        let(:sort) { nil }
+
+        subject { get api("/projects/#{project.id}/deployments?order_by=#{order_by}&sort=#{sort}", user) }
+
+        def expect_deployments(ordered_deployments)
+          json_response.each_with_index do |deployment_json, index|
+            expect(deployment_json['id']).to eq(public_send(ordered_deployments[index]).id)
+          end
+        end
+
+        before do
+          subject
+        end
+
+        where(:order_by, :sort, :ordered_deployments) do
+          'created_at' | 'asc'  | [:deployment_3, :deployment_2, :deployment_1]
+          'created_at' | 'desc' | [:deployment_1, :deployment_2, :deployment_3]
+          'id'         | 'asc'  | [:deployment_1, :deployment_2, :deployment_3]
+          'id'         | 'desc' | [:deployment_3, :deployment_2, :deployment_1]
+          'iid'        | 'asc'  | [:deployment_3, :deployment_1, :deployment_2]
+          'iid'        | 'desc' | [:deployment_2, :deployment_1, :deployment_3]
+          'ref'        | 'asc'  | [:deployment_2, :deployment_3, :deployment_1]
+          'ref'        | 'desc' | [:deployment_1, :deployment_2, :deployment_3]
+        end
+
+        with_them do
+          it 'returns the deployments ordered' do
+            expect_deployments(ordered_deployments)
+          end
+        end
       end
     end
@@ -34,6 +75,9 @@ describe API::Deployments do
   end
   describe 'GET /projects/:id/deployments/:deployment_id' do
+    let(:project)     { deployment.environment.project }
+    let!(:deployment) { create(:deployment) }
+
     context 'as a member of the project' do
       it 'returns the projects deployment' do
         get api("/projects/#{project.id}/deployments/#{deployment.id}", user)