Commit c0e77f7c authored by blackst0ne's avatar blackst0ne Committed by Douwe Maan

Resolve "Expand API: Render an arbitrary Markdown document"

parent 9f863dbe
---
title: Add API endpoint to render markdown text
merge_request: 18926
author: "@blackst0ne"
type: added
......@@ -33,6 +33,7 @@ following locations:
- [Jobs](jobs.md)
- [Keys](keys.md)
- [Labels](labels.md)
- [Markdown](markdown.md)
- [Merge Requests](merge_requests.md)
- [Project milestones](milestones.md)
- [Group milestones](group_milestones.md)
......
# Markdown API
> [Introduced][ce-18926] in GitLab 11.0.
Available only in APIv4.
## Render an arbitrary Markdown document
```
POST /api/v4/markdown
```
| Attribute | Type | Required | Description |
| --------- | ------- | ------------- | ------------------------------------------ |
| `text` | string | yes | The markdown text to render |
| `gfm` | boolean | no (optional) | Render text using GitLab Flavored Markdown. Default is `false` |
| `project` | string | no (optional) | Use `project` as a context when creating references using GitLab Flavored Markdown. [Authentication](README.html#authentication) is required if a project is not public. |
```bash
curl --header Content-Type:application/json --data '{"text":"Hello world! :tada:", "gfm":true, "project":"group_example/project_example"}' https://gitlab.example.com/api/v4/markdown
```
Response example:
```json
{ "html": "<p dir=\"auto\">Hello world! <gl-emoji title=\"party popper\" data-name=\"tada\" data-unicode-version=\"6.0\">🎉</gl-emoji></p>" }
```
[ce-18926]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18926
......@@ -140,6 +140,7 @@ module API
mount ::API::Keys
mount ::API::Labels
mount ::API::Lint
mount ::API::Markdown
mount ::API::Members
mount ::API::MergeRequestDiffs
mount ::API::MergeRequests
......
module API
class Markdown < Grape::API
params do
requires :text, type: String, desc: "The markdown text to render"
optional :gfm, type: Boolean, desc: "Render text using GitLab Flavored Markdown"
optional :project, type: String, desc: "The full path of a project to use as the context when creating references using GitLab Flavored Markdown"
end
resource :markdown do
desc "Render markdown text" do
detail "This feature was introduced in GitLab 11.0."
end
post do
# Explicitly set CommonMark as markdown engine to use.
# Remove this set when https://gitlab.com/gitlab-org/gitlab-ce/issues/43011 is done.
context = { markdown_engine: :common_mark, only_path: false }
if params[:project]
project = Project.find_by_full_path(params[:project])
not_found!("Project") unless can?(current_user, :read_project, project)
context[:project] = project
else
context[:skip_project_check] = true
end
context[:pipeline] = params[:gfm] ? :full : :plain_markdown
{ html: Banzai.render(params[:text], context) }
end
end
end
end
......@@ -73,7 +73,7 @@ module Banzai
#
# Note that while the key might exist, its value could be nil!
def validate
needs :project
needs :project unless skip_project_check?
end
# Iterates over all <a> and text() nodes in a document.
......
......@@ -42,9 +42,9 @@ module Banzai
end
def self.transform_context(context)
context.merge(
only_path: true,
context[:only_path] = true unless context.key?(:only_path)
context.merge(
# EmojiFilter
asset_host: Gitlab::Application.config.asset_host,
asset_root: Gitlab.config.gitlab.base_url
......
require "spec_helper"
describe API::Markdown do
RSpec::Matchers.define_negated_matcher :exclude, :include
describe "POST /markdown" do
let(:user) {} # No-op. It gets overwritten in the contexts below.
before do
post api("/markdown", user), params
end
shared_examples "rendered markdown text without GFM" do
it "renders markdown text" do
expect(response).to have_http_status(201)
expect(response.headers["Content-Type"]).to eq("application/json")
expect(json_response).to be_a(Hash)
expect(json_response["html"]).to eq("<p>#{text}</p>")
end
end
shared_examples "404 Project Not Found" do
it "responses with 404 Not Found" do
expect(response).to have_http_status(404)
expect(response.headers["Content-Type"]).to eq("application/json")
expect(json_response).to be_a(Hash)
expect(json_response["message"]).to eq("404 Project Not Found")
end
end
context "when arguments are invalid" do
context "when text is missing" do
let(:params) { {} }
it "responses with 400 Bad Request" do
expect(response).to have_http_status(400)
expect(response.headers["Content-Type"]).to eq("application/json")
expect(json_response).to be_a(Hash)
expect(json_response["error"]).to eq("text is missing")
end
end
context "when project is not found" do
let(:params) { { text: "Hello world!", gfm: true, project: "Dummy project" } }
it_behaves_like "404 Project Not Found"
end
end
context "when arguments are valid" do
set(:project) { create(:project) }
set(:issue) { create(:issue, project: project) }
let(:text) { ":tada: Hello world! :100: #{issue.to_reference}" }
context "when not using gfm" do
context "without project" do
let(:params) { { text: text } }
it_behaves_like "rendered markdown text without GFM"
end
context "with project" do
let(:params) { { text: text, project: project.full_path } }
context "when not authorized" do
it_behaves_like "404 Project Not Found"
end
context "when authorized" do
let(:user) { project.owner }
it_behaves_like "rendered markdown text without GFM"
end
end
end
context "when using gfm" do
context "without project" do
let(:params) { { text: text, gfm: true } }
it "renders markdown text" do
expect(response).to have_http_status(201)
expect(response.headers["Content-Type"]).to eq("application/json")
expect(json_response).to be_a(Hash)
expect(json_response["html"]).to include("Hello world!")
.and include('data-name="tada"')
.and include('data-name="100"')
.and include("#1")
.and exclude("<a href=\"#{IssuesHelper.url_for_issue(issue.iid, project)}\"")
.and exclude("#1</a>")
end
end
context "with project" do
let(:params) { { text: text, gfm: true, project: project.full_path } }
let(:user) { project.owner }
it "renders markdown text" do
expect(response).to have_http_status(201)
expect(response.headers["Content-Type"]).to eq("application/json")
expect(json_response).to be_a(Hash)
expect(json_response["html"]).to include("Hello world!")
.and include('data-name="tada"')
.and include('data-name="100"')
.and include("<a href=\"#{IssuesHelper.url_for_issue(issue.iid, project)}\"")
.and include("#1</a>")
end
end
end
end
end
end
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment