Add API support for wiki pages

changelogs/unreleased/wiki_api.yml

+---
+title: Add API support for wiki pages
+merge_request: 13372
+author: Vitaliy @blackst0ne Klachkov
+type: added

doc/api/README.md

@@ -58,6 +58,7 @@ following locations:
 - [Validate CI configuration](lint.md)
 - [V3 to V4](v3_to_v4.md)
 - [Version](version.md)
+- [Wikis](wikis.md)
 
 ## Road to GraphQL
 

doc/api/wikis.md

+# Wikis API
+
+> [Introduced][ce-13372] in GitLab 10.0.
+
+Available only in APIv4.
+
+## List wiki pages
+
+Get all wiki pages for a given project.
+
+```
+GET /projects/:id/wikis
+```
+
+| Attribute | Type    | Required | Description           |
+| --------- | ------- | -------- | --------------------- |
+| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `with_content`      | boolean    | no      | Include pages' content  |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/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 project.
+
+```
+GET /projects/:id/wikis/:slug
+```
+
+| Attribute | Type    | Required | Description           |
+| --------- | ------- | -------- | --------------------- |
+| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `slug` | string  | yes       | The slug (a unique string) of the wiki page |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/wikis/home
+```
+
+Example response:
+
+```json
+[
+  {
+    "content" : "home page",
+    "format" : "markdown",
+    "slug" : "home",
+    "title" : "home"
+  }
+]
+```
+
+## Create a new wiki page
+
+Creates a new wiki page for the given repository with the given title, slug, and content.
+
+```
+POST /projects/:id/wikis
+```
+
+| Attribute     | Type    | Required | Description                  |
+| ------------- | ------- | -------- | ---------------------------- |
+| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](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`, and `asciidoc` |
+
+```bash
+curl --data "format=rdoc&title=Hello&content=Hello world" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis"
+```
+
+Example response:
+
+```json
+{ 
+  "content" : "Hello world",
+  "format" : "markdown",
+  "slug" : "Hello",
+  "title" : "Hello"
+} 
+```
+
+## Edit an existing wiki page
+
+Updates an existing wiki page. At least one parameter is required to update the wiki page.
+
+```
+PUT /projects/:id/wikis/:slug
+```
+
+| Attribute       | Type    | Required                          | Description                      |
+| --------------- | ------- | --------------------------------- | -------------------------------  |
+| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](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`, and `asciidoc` |
+| `slug` | string  | yes       | The slug (a unique string) of the wiki page |
+
+
+```bash
+curl --request PUT --data "format=rdoc&content=documentation&title=Docs" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo"
+```
+
+Example response:
+
+```json
+{
+  "content" : "documentation",
+  "format" : "markdown",
+  "slug" : "Docs",
+  "title" : "Docs"
+}
+```
+
+## Delete a wiki page
+
+Deletes a wiki page with a given slug.
+
+```
+DELETE /projects/:id/wikis/:slug
+```
+
+| Attribute | Type    | Required | Description           |
+| --------- | ------- | -------- | --------------------- |
+| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `slug` | string  | yes       | The slug (a unique string) of the wiki page |
+
+```bash
+curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo"
+```
+
+On success the HTTP status code is `204` and no JSON response is expected. 

lib/api/api.rb

@@ -143,6 +143,7 @@ module API
     mount ::API::Variables
     mount ::API::GroupVariables
     mount ::API::Version
+    mount ::API::Wikis
 
     route :any, '*path' do
       error!('404 Not Found', 404)

lib/api/entities.rb

 module API
   module Entities
+    class WikiPageBasic < Grape::Entity
+      expose :format
+      expose :slug
+      expose :title
+    end
+
+    class WikiPage < WikiPageBasic
+      expose :content
+    end
+
     class UserSafe < Grape::Entity
       expose :name, :username
     end

lib/api/helpers.rb

@@ -35,6 +35,12 @@ module API
       @project ||= find_project!(params[:id])
     end
 
+    def wiki_page
+      page = user_project.wiki.find_page(params[:slug])
+
+      page || not_found!('Wiki Page')
+    end
+
     def available_labels
       @available_labels ||= LabelsFinder.new(current_user, project_id: user_project.id).execute
     end

lib/api/wikis.rb

+module API
+  class Wikis < Grape::API
+    helpers do
+      params :wiki_page_params do
+        requires :content, type: String, desc: 'Content of a wiki page'
+        requires :title, type: String, desc: 'Title of a wiki page'
+        optional :format,
+          type: String,
+          values: ProjectWiki::MARKUPS.values.map(&:to_s),
+          default: 'markdown',
+          desc: 'Format of a wiki page. Available formats are markdown, rdoc, and asciidoc'
+      end
+    end
+
+    resource :projects, requirements: API::PROJECT_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
+        present user_project.wiki.pages, with: entity
+      end
+
+      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
+
+        present wiki_page, with: Entities::WikiPage
+      end
+
+      desc 'Create a wiki page' do
+        success Entities::WikiPage
+      end
+      params do
+        use :wiki_page_params
+      end
+      post ':id/wikis' do
+        authorize! :create_wiki, user_project
+
+        page = WikiPages::CreateService.new(user_project, current_user, params).execute
+
+        if page.valid?
+          present page, with: Entities::WikiPage
+        else
+          render_validation_error!(page)
+        end
+      end
+
+      desc 'Update a wiki page' do
+        success Entities::WikiPage
+      end
+      params do
+        use :wiki_page_params
+      end
+      put ':id/wikis/:slug' do
+        authorize! :create_wiki, user_project
+
+        page = WikiPages::UpdateService.new(user_project, current_user, params).execute(wiki_page)
+
+        if page.valid?
+          present page, with: Entities::WikiPage
+        else
+          render_validation_error!(page)
+        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
+
+        status 204
+        WikiPages::DestroyService.new(user_project, current_user).execute(wiki_page)
+      end
+    end
+  end
+end