Merge branch 'ajk-group-wiki-attachments' into 'master'

[Group Wiki] Update attachment API to support Group Level Wiki

Closes #212199

See merge request gitlab-org/gitlab!34232

doc/api/group_wikis.md

+# Wikis API
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212199) in GitLab 13.2.
+
+Available only in APIv4.
+
+## List wiki pages
+
+List all wiki pages for a given group.
+
+```plaintext
+GET /groups/:id/wikis
+```
+
+| Attribute      | Type           | Required | Description                                                                   |
+| ---------      | -------        | -------- | ---------------------                                                         |
+| `id`           | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+| `with_content` | boolean        | no       | Include pages' content                                                        |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/wikis?with_content=1"
+```
+
+Example response:
+
+```json
+[
+  {
+    "content" : "Here is an instruction how to deploy this project.",
+    "format" : "markdown",
+    "slug" : "deploy",
+    "title" : "deploy"
+  },
+  {
+    "content" : "Our development process is described here.",
+    "format" : "markdown",
+    "slug" : "development",
+    "title" : "development"
+  },{
+    "content" : "*  [Deploy](deploy)\n*  [Development](development)",
+    "format" : "markdown",
+    "slug" : "home",
+    "title" : "home"
+  }
+]
+```
+
+## Get a wiki page
+
+Get a wiki page for a given group.
+
+```plaintext
+GET /groups/:id/wikis/:slug
+```
+
+| Attribute | Type           | Required | Description                                                                   |
+| --------- | -------        | -------- | ---------------------                                                         |
+| `id`      | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+| `slug`    | string         | yes      | The slug (a unique string) of the wiki page                                   |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/wikis/home"
+```
+
+Example response:
+
+```json
+{
+  "content" : "home page",
+  "format" : "markdown",
+  "slug" : "home",
+  "title" : "home"
+}
+```
+
+## Create a new wiki page
+
+Create a new wiki page for the given repository with the given title, slug, and content.
+
+```plaintext
+POST /projects/:id/wikis
+```
+
+| Attribute     | Type           | Required | Description                                                                                            |
+| ------------- | -------        | -------- | ----------------------------                                                                           |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding)                          |
+| `content`     | string         | yes      | The content of the wiki page                                                                           |
+| `title`       | string         | yes      | The title of the wiki page                                                                             |
+| `format`      | string         | no       | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` |
+
+```shell
+curl --data "format=rdoc&title=Hello&content=Hello world" \
+     --header "PRIVATE-TOKEN: <your_access_token>" \
+     "https://gitlab.example.com/api/v4/groups/1/wikis"
+```
+
+Example response:
+
+```json
+{
+  "content" : "Hello world",
+  "format" : "markdown",
+  "slug" : "Hello",
+  "title" : "Hello"
+}
+```
+
+## Edit an existing wiki page
+
+Update an existing wiki page. At least one parameter is required to update the wiki page.
+
+```plaintext
+PUT /groups/:id/wikis/:slug
+```
+
+| Attribute       | Type           | Required                          | Description                                                                                            |
+| --------------- | -------        | --------------------------------- | -------------------------------                                                                        |
+| `id`            | integer/string | yes                               | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding)                          |
+| `content`       | string         | yes if `title` is not provided    | The content of the wiki page                                                                           |
+| `title`         | string         | yes if `content` is not provided  | The title of the wiki page                                                                             |
+| `format`        | string         | no                                | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` |
+| `slug`          | string         | yes                               | The slug (a unique identifier) of the wiki page                                                        |
+
+```shell
+curl --request PUT --data "format=rdoc&content=documentation&title=Docs" \
+     --header "PRIVATE-TOKEN: <your_access_token>" \
+     "https://gitlab.example.com/api/v4/groups/1/wikis/foo"
+```
+
+Example response:
+
+```json
+{
+  "content" : "documentation",
+  "format" : "markdown",
+  "slug" : "Docs",
+  "title" : "Docs"
+}
+```
+
+## Delete a wiki page
+
+Delete a wiki page with a given slug.
+
+```plaintext
+DELETE /groups/:id/wikis/:slug
+```
+
+| Attribute | Type           | Required | Description                                                                   |
+| --------- | -------        | -------- | ---------------------                                                         |
+| `id`      | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+| `slug`    | string         | yes      | The slug (a unique identifier) of the wiki page                               |
+
+```shell
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/wikis/foo"
+```
+
+On success the HTTP status code is `204` and no JSON response is expected.
+
+## Upload an attachment to the wiki repository
+
+Upload a file to the attachment folder inside the wiki's repository. The
+attachment folder is the `uploads` folder.
+
+```plaintext
+POST /groups/:id/wikis/attachments
+```
+
+| Attribute     | Type           | Required | Description                                                                   |
+| ------------- | -------        | -------- | ----------------------------                                                  |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
+| `file`        | string         | yes      | The attachment to be uploaded                                                 |
+| `branch`      | string         | no       | The name of the branch. Defaults to the wiki repository default branch        |
+
+To upload a file from your filesystem, use the `--form` argument. This causes
+cURL to post data using the header `Content-Type: multipart/form-data`.
+The `file=` parameter must point to a file on your filesystem and be preceded
+by `@`. For example:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "file=@dk.png" "https://gitlab.example.com/api/v4/groups/1/wikis/attachments"
+```
+
+Example response:
+
+```json
+{
+  "file_name" : "dk.png",
+  "file_path" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png",
+  "branch" : "master",
+  "link" : {
+    "url" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png",
+    "markdown" : "![dk](uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png)"
+  }
+}
+```

ee/changelogs/unreleased/ajk-group-wiki-attachments.yml

+---
+title: Add group wiki REST API
+merge_request: 34232
+author:
+type: added

ee/lib/ee/api/helpers/wikis_helpers.rb

+# frozen_string_literal: true
+
+module EE
+  module API
+    module Helpers
+      module WikisHelpers
+        extend ActiveSupport::Concern
+        extend ::Gitlab::Utils::Override
+
+        class_methods do
+          def wiki_resource_kinds
+            [:groups, *super]
+          end
+        end
+
+        override :find_container
+        def find_container(kind)
+          return user_group if kind == :groups
+
+          super
+        end
+      end
+    end
+  end
+end

lib/api/helpers.rb

@@ -79,12 +79,6 @@ module API
       @project ||= find_project!(params[:id])
     end
 
-    def wiki_page
-      page = ProjectWiki.new(user_project, current_user).find_page(params[:slug])
-
-      page || not_found!('Wiki Page')
-    end
-
     def available_labels_for(label_parent, include_ancestor_groups: true)
       search_params = { include_ancestor_groups: include_ancestor_groups }
 

lib/api/helpers/wikis_helpers.rb

+# frozen_string_literal: true
+
+module API
+  module Helpers
+    module WikisHelpers
+      def self.wiki_resource_kinds
+        [:projects]
+      end
+
+      def find_container(kind)
+        return user_project if kind == :projects
+
+        raise "Unknown wiki container #{kind}"
+      end
+
+      def wiki_page
+        Wiki.for_container(container, current_user).find_page(params[:slug]) || not_found!('Wiki Page')
+      end
+
+      def commit_params(attrs)
+        base_params = { branch_name: attrs[:branch] }
+        file_details = case attrs[:file]
+                       when Hash # legacy format: TODO remove when we drop support for non accelerated uploads
+                         { file_name: attrs[:file][:filename], file_content: attrs[:file][:tempfile].read }
+                       else
+                         { file_name: attrs[:file].original_filename, file_content: attrs[:file].read }
+                       end
+
+        base_params.merge(file_details)
+      end
+    end
+  end
+end
+
+API::Helpers::WikisHelpers.prepend_if_ee('EE::API::Helpers::WikisHelpers')

lib/api/wikis.rb

@@ -2,24 +2,10 @@
 
 module API
   class Wikis < Grape::API
+    helpers ::API::Helpers::WikisHelpers
+
     helpers do
-      def commit_params(attrs)
-        # In order to avoid service disruption this can work with an old workhorse without the acceleration
-        # the first branch of this if must be removed when we drop support for non accelerated uploads
-        if attrs[:file].is_a?(Hash)
-          {
-            file_name: attrs[:file][:filename],
-            file_content: attrs[:file][:tempfile].read,
-            branch_name: attrs[:branch]
-          }
-        else
-          {
-            file_name: attrs[:file].original_filename,
-            file_content: attrs[:file].read,
-            branch_name: attrs[:branch]
-          }
-        end
-      end
+      attr_reader :container
 
       params :common_wiki_page_params do
         optional :format,
@@ -32,108 +18,118 @@ module API
 
     WIKI_ENDPOINT_REQUIREMENTS = API::NAMESPACE_OR_PROJECT_REQUIREMENTS.merge(slug: API::NO_SLASH_URL_PART_REGEX)
 
-    resource :projects, requirements: WIKI_ENDPOINT_REQUIREMENTS do
-      desc 'Get a list of wiki pages' do
-        success Entities::WikiPageBasic
-      end
-      params do
-        optional :with_content, type: Boolean, default: false, desc: "Include pages' content"
-      end
-      get ':id/wikis' do
-        authorize! :read_wiki, user_project
-
-        entity = params[:with_content] ? Entities::WikiPage : Entities::WikiPageBasic
+    ::API::Helpers::WikisHelpers.wiki_resource_kinds.each do |container_resource|
+      resource container_resource, requirements: WIKI_ENDPOINT_REQUIREMENTS do
+        after_validation do
+          @container = Gitlab::Lazy.new { find_container(container_resource) }
+        end
 
-        present user_project.wiki.list_pages(load_content: params[:with_content]), with: entity
-      end
+        desc 'Get a list of wiki pages' do
+          success Entities::WikiPageBasic
+        end
+        params do
+          optional :with_content, type: Boolean, default: false, desc: "Include pages' content"
+        end
+        get ':id/wikis' do
+          authorize! :read_wiki, container
 
-      desc 'Get a wiki page' do
-        success Entities::WikiPage
-      end
-      params do
-        requires :slug, type: String, desc: 'The slug of a wiki page'
-      end
-      get ':id/wikis/:slug' do
-        authorize! :read_wiki, user_project
+          entity = params[:with_content] ? Entities::WikiPage : Entities::WikiPageBasic
 
-        present wiki_page, with: Entities::WikiPage
-      end
+          present container.wiki.list_pages(load_content: params[:with_content]), with: entity
+        end
 
-      desc 'Create a wiki page' do
-        success Entities::WikiPage
-      end
-      params do
-        requires :title, type: String, desc: 'Title of a wiki page'
-        requires :content, type: String, desc: 'Content of a wiki page'
-        use :common_wiki_page_params
-      end
-      post ':id/wikis' do
-        authorize! :create_wiki, user_project
+        desc 'Get a wiki page' do
+          success Entities::WikiPage
+        end
+        params do
+          requires :slug, type: String, desc: 'The slug of a wiki page'
+        end
+        get ':id/wikis/:slug' do
+          authorize! :read_wiki, container
 
-        page = WikiPages::CreateService.new(container: user_project, current_user: current_user, params: params).execute
+          present wiki_page, with: Entities::WikiPage
+        end
 
-        if page.valid?
-          present page, with: Entities::WikiPage
-        else
-          render_validation_error!(page)
+        desc 'Create a wiki page' do
+          success Entities::WikiPage
         end
-      end
+        params do
+          requires :title, type: String, desc: 'Title of a wiki page'
+          requires :content, type: String, desc: 'Content of a wiki page'
+          use :common_wiki_page_params
+        end
+        post ':id/wikis' do
+          authorize! :create_wiki, container
 
-      desc 'Update a wiki page' do
-        success Entities::WikiPage
-      end
-      params do
-        optional :title, type: String, desc: 'Title of a wiki page'
-        optional :content, type: String, desc: 'Content of a wiki page'
-        use :common_wiki_page_params
-        at_least_one_of :content, :title, :format
-      end
-      put ':id/wikis/:slug' do
-        authorize! :create_wiki, user_project
+          page = WikiPages::CreateService.new(container: container, current_user: current_user, params: params).execute
 
-        page = WikiPages::UpdateService.new(container: user_project, current_user: current_user, params: params).execute(wiki_page)
+          if page.valid?
+            present page, with: Entities::WikiPage
+          else
+            render_validation_error!(page)
+          end
+        end
 
-        if page.valid?
-          present page, with: Entities::WikiPage
-        else
-          render_validation_error!(page)
+        desc 'Update a wiki page' do
+          success Entities::WikiPage
+        end
+        params do
+          optional :title, type: String, desc: 'Title of a wiki page'
+          optional :content, type: String, desc: 'Content of a wiki page'
+          use :common_wiki_page_params
+          at_least_one_of :content, :title, :format
+        end
+        put ':id/wikis/:slug' do
+          authorize! :create_wiki, container
+
+          page = WikiPages::UpdateService
+            .new(container: container, current_user: current_user, params: params)
+            .execute(wiki_page)
+
+          if page.valid?
+            present page, with: Entities::WikiPage
+          else
+            render_validation_error!(page)
+          end
         end
-      end
 
-      desc 'Delete a wiki page'
-      params do
-        requires :slug, type: String, desc: 'The slug of a wiki page'
-      end
-      delete ':id/wikis/:slug' do
-        authorize! :admin_wiki, user_project
+        desc 'Delete a wiki page'
+        params do
+          requires :slug, type: String, desc: 'The slug of a wiki page'
+        end
+        delete ':id/wikis/:slug' do
+          authorize! :admin_wiki, container
 
-        WikiPages::DestroyService.new(container: user_project, current_user: current_user).execute(wiki_page)
+          WikiPages::DestroyService
+            .new(container: container, current_user: current_user)
+            .execute(wiki_page)
 
-        no_content!
-      end
+          no_content!
+        end
 
-      desc 'Upload an attachment to the wiki repository' do
-        detail 'This feature was introduced in GitLab 11.3.'
-        success Entities::WikiAttachment
-      end
-      params do
-        requires :file, types: [::API::Validations::Types::SafeFile, ::API::Validations::Types::WorkhorseFile], desc: 'The attachment file to be uploaded'
-        optional :branch, type: String, desc: 'The name of the branch'
-      end
-      post ":id/wikis/attachments" do
-        authorize! :create_wiki, user_project
-
-        result = ::Wikis::CreateAttachmentService.new(
-          container: user_project,
-          current_user: current_user,
-          params: commit_params(declared_params(include_missing: false))
-        ).execute
-
-        if result[:status] == :success
-          status(201)
-          present OpenStruct.new(result[:result]), with: Entities::WikiAttachment
-        else
-          render_api_error!(result[:message], 400)
+        desc 'Upload an attachment to the wiki repository' do
+          detail 'This feature was introduced in GitLab 11.3.'
+          success Entities::WikiAttachment
+        end
+        params do
+          requires :file, types: [::API::Validations::Types::SafeFile, ::API::Validations::Types::WorkhorseFile], desc: 'The attachment file to be uploaded'
+          optional :branch, type: String, desc: 'The name of the branch'
+        end
+        post ":id/wikis/attachments" do
+          authorize! :create_wiki, container
+
+          result = ::Wikis::CreateAttachmentService.new(
+            container: container,
+            current_user: current_user,
+            params: commit_params(declared_params(include_missing: false))
+          ).execute
+
+          if result[:status] == :success
+            status(201)
+            present OpenStruct.new(result[:result]), with: Entities::WikiAttachment
+          else
+            render_api_error!(result[:message], 400)
+          end
         end
       end
     end

spec/support/shared_examples/lib/wikis_api_examples.rb

+# frozen_string_literal: true
+
+RSpec.shared_examples_for 'wikis API returns list of wiki pages' do
+  context 'when wiki has pages' do
+    let!(:pages) do
+      [create(:wiki_page, wiki: wiki, title: 'page1', content: 'content of page1'),
+       create(:wiki_page, wiki: wiki, title: 'page2.with.dot', content: 'content of page2')]
+    end
+
+    it 'returns the list of wiki pages without content' do
+      get api(url, user)
+
+      expect(response).to have_gitlab_http_status(:ok)
+      expect(json_response.size).to eq(2)
+
+      json_response.each_with_index do |page, index|
+        expect(page.keys).to match_array(expected_keys_without_content)
+        expect(page['slug']).to eq(pages[index].slug)
+        expect(page['title']).to eq(pages[index].title)
+      end
+    end
+
+    it 'returns the list of wiki pages with content' do
+      get api(url, user), params: { with_content: 1 }
+
+      expect(response).to have_gitlab_http_status(:ok)
+      expect(json_response.size).to eq(2)
+
+      json_response.each_with_index do |page, index|
+        expect(page.keys).to match_array(expected_keys_with_content)
+        expect(page['content']).to eq(pages[index].content)
+        expect(page['slug']).to eq(pages[index].slug)
+        expect(page['title']).to eq(pages[index].title)
+      end
+    end
+  end
+
+  it 'return the empty list of wiki pages' do
+    get api(url, user)
+
+    expect(response).to have_gitlab_http_status(:ok)
+    expect(json_response.size).to eq(0)
+  end
+end
+
+RSpec.shared_examples_for 'wikis API returns wiki page' do
+  it 'returns the wiki page' do
+    expect(response).to have_gitlab_http_status(:ok)
+    expect(json_response.size).to eq(4)
+    expect(json_response.keys).to match_array(expected_keys_with_content)
+    expect(json_response['content']).to eq(page.content)
+    expect(json_response['slug']).to eq(page.slug)
+    expect(json_response['title']).to eq(page.title)
+  end
+end
+
+RSpec.shared_examples_for 'wikis API creates wiki page' do
+  it 'creates the wiki page' do
+    post(api(url, user), params: payload)
+
+    expect(response).to have_gitlab_http_status(:created)
+    expect(json_response.size).to eq(4)
+    expect(json_response.keys).to match_array(expected_keys_with_content)
+    expect(json_response['content']).to eq(payload[:content])
+    expect(json_response['slug']).to eq(payload[:title].tr(' ', '-'))
+    expect(json_response['title']).to eq(payload[:title])
+    expect(json_response['rdoc']).to eq(payload[:rdoc])
+  end
+
+  [:title, :content].each do |part|
+    it "responds with validation error on empty #{part}" do
+      payload.delete(part)
+
+      post(api(url, user), params: payload)
+
+      expect(response).to have_gitlab_http_status(:bad_request)
+      expect(json_response.size).to eq(1)
+      expect(json_response['error']).to eq("#{part} is missing")
+    end
+  end
+end
+
+RSpec.shared_examples_for 'wikis API updates wiki page' do
+  it 'updates the wiki page' do
+    put(api(url, user), params: payload)
+
+    expect(response).to have_gitlab_http_status(:ok)
+    expect(json_response.size).to eq(4)
+    expect(json_response.keys).to match_array(expected_keys_with_content)
+    expect(json_response['content']).to eq(payload[:content])
+    expect(json_response['slug']).to eq(payload[:title].tr(' ', '-'))
+    expect(json_response['title']).to eq(payload[:title])
+  end
+
+  [:title, :content, :format].each do |part|
+    it "updates with wiki with missing #{part}" do
+      payload.delete(part)
+
+      put(api(url, user), params: payload)
+
+      expect(response).to have_gitlab_http_status(:ok)
+    end
+  end
+end
+
+RSpec.shared_examples_for 'wiki API 403 Forbidden' do
+  it 'returns 403 Forbidden' do
+    expect(response).to have_gitlab_http_status(:forbidden)
+    expect(json_response.size).to eq(1)
+    expect(json_response['message']).to eq('403 Forbidden')
+  end
+end
+
+RSpec.shared_examples_for 'wiki API 404 Wiki Page Not Found' do
+  it 'returns 404 Wiki Page Not Found' do
+    expect(response).to have_gitlab_http_status(:not_found)
+    expect(json_response.size).to eq(1)
+    expect(json_response['message']).to eq('404 Wiki Page Not Found')
+  end
+end
+
+RSpec.shared_examples_for 'wiki API 404 Not Found' do |what|
+  it "returns 404 #{what} Not Found" do
+    expect(response).to have_gitlab_http_status(:not_found)
+    expect(json_response.size).to eq(1)
+    expect(json_response['message']).to eq("404 #{what} Not Found")
+  end
+end
+
+RSpec.shared_examples_for 'wiki API 204 No Content' do
+  it 'returns 204 No Content' do
+    expect(response).to have_gitlab_http_status(:no_content)
+  end
+end
+
+RSpec.shared_examples_for 'wiki API uploads wiki attachment' do
+  it 'pushes attachment to the wiki repository' do
+    allow(SecureRandom).to receive(:hex).and_return('fixed_hex')
+
+    workhorse_post_with_file(api(url, user), file_key: :file, params: payload)
+
+    expect(response).to have_gitlab_http_status(:created)
+    expect(json_response).to eq result_hash.deep_stringify_keys
+  end
+
+  it 'responds with validation error on empty file' do
+    payload.delete(:file)
+
+    post(api(url, user), params: payload)
+
+    expect(response).to have_gitlab_http_status(:bad_request)
+    expect(json_response.size).to eq(1)
+    expect(json_response['error']).to eq('file is missing')
+  end
+
+  it 'responds with validation error on invalid temp file' do
+    payload[:file] = { tempfile: '/etc/hosts' }
+
+    post(api(url, user), params: payload)
+
+    expect(response).to have_gitlab_http_status(:bad_request)
+    expect(json_response.size).to eq(1)
+    expect(json_response['error']).to eq('file is invalid')
+  end
+
+  it 'is backward compatible with regular multipart uploads' do
+    allow(SecureRandom).to receive(:hex).and_return('fixed_hex')
+
+    post(api(url, user), params: payload)
+
+    expect(response).to have_gitlab_http_status(:created)
+    expect(json_response).to eq result_hash.deep_stringify_keys
+  end
+end