decidim · microstudi · Jan 31, 2020 · Dec 13, 2019 · Dec 13, 2019 · Dec 13, 2019
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,7 @@ Decidim::Blogs::Post.find_each(&:add_to_index_as_search_resource)
 
 **Added**:
 
+- **decidim-api**: Added documentation to use the API (newcomers friendly). [\#5582](https://github.com/decidim/decidim/pull/5582)
 - **many modules**: Added all spaces and many entities to global search, see Upgrade notes for more detail. [\#5469](https://github.com/decidim/decidim/pull/5469)
 - **decidim-core**: Add weight to categories and sort them by that field. [\#5505](https://github.com/decidim/decidim/pull/5505)
 - **decidim-proposals**: Add: Additional sorting filters for proposals index. [\#5506](https://github.com/decidim/decidim/pull/5506)

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -39,6 +39,7 @@ PATH
       graphiql-rails (~> 1.4, < 1.5)
       graphql (~> 1.9)
       rack-cors (~> 1.0)
+      redcarpet (~> 3.4)
       sprockets-es6 (~> 0.9.2)
     decidim-assemblies (0.20.0.dev)
       decidim-core (= 0.20.0.dev)
@@ -405,7 +406,7 @@ GEM
     graphiql-rails (1.4.11)
       railties
       sprockets-rails
-    graphql (1.9.14)
+    graphql (1.9.16)
     hashdiff (1.0.0)
     hashie (3.6.0)
     highline (2.0.3)

diff --git a/decidim-api/app/assets/stylesheets/decidim/api/docs.scss b/decidim-api/app/assets/stylesheets/decidim/api/docs.scss
@@ -0,0 +1,61 @@
+body{
+  max-width: 1200px;
+}
+
+.intro,
+.info{
+  margin-left: 270px;
+  color: #333;
+}
+
+.info{
+  li{
+    margin-bottom: 1rem;
+  }
+
+  h3{
+    margin-top: 2em;
+  }
+}
+
+.version{
+  display: inline-block;
+  font-size: .8rem;
+  margin-right: 1rem;
+  padding: 3px 7px;
+  background: #f33;
+  border-radius: 10px;
+  margin-top: 5px;
+  color: white;
+}
+
+@media only screen and (max-width: 767px){
+  .intro,
+  .info{
+    margin: 10px;
+  }
+}
+
+code{
+  font-size: .8em;
+  background: #ddd;
+  padding: .1em;
+}
+
+pre{
+  padding: .5rem;
+  background: #f0f0f0;
+  border: 1px solid #e8e8e8;
+
+  code{
+    background: none;
+  }
+}
+
+blockquote{
+  border-left: 3px solid burlywood;
+  padding: .1em 0 .1em 1rem;
+  margin: 1rem 0;
+  background: #f9f7f5;
+  width: 100%;
+}
diff --git a/decidim-api/app/helpers/decidim/api/application_helper.rb b/decidim-api/app/helpers/decidim/api/application_helper.rb
@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "redcarpet"
+
+module Decidim
+  module Api
+    # Custom helpers, scoped to the api engine.
+    #
+    module ApplicationHelper
+      def render_doc(file)
+        md_render File.read(File.join(File.dirname(__FILE__), "../../../../docs", "#{file}.md"))
+      end
+
+      def md_render(text)
+        text = Redcarpet::Markdown.new(markdown, autolink: true, tables: true, fenced_code_blocks: true).render(text)
+        text.html_safe
+      end
+
+      def markdown
+        @markdown ||= Redcarpet::Render::HTML.new
+      end
+    end
+  end
+end
diff --git a/decidim-api/app/views/decidim/api/documentation/show.html.erb b/decidim-api/app/views/decidim/api/documentation/show.html.erb
@@ -1,6 +1,15 @@
-<div style="text-align: center;">
+
+<div class="intro">
+  <div class="version">Decidim <%= Decidim.version %></div>
+
   <h1><%= current_organization.name %> API documentation</h1>
-  <%= link_to "Explore the API interactively with GraphiQL", graphiql_path %>
+  <% if defined?(graphiql_path) %>
+    <%= link_to "Explore the API interactively with GraphiQL", graphiql_path %>
+  <% end %>
+</div>
+
+<div class="info">
+  <%= render_doc("usage") %>
 </div>
 
 <div id="documentation"></div>

diff --git a/decidim-api/app/views/layouts/decidim/api/documentation.html.erb b/decidim-api/app/views/layouts/decidim/api/documentation.html.erb
@@ -2,6 +2,9 @@
   <head>
     <title><%= current_organization.name %> - API Documentation</title>
     <%= javascript_include_tag "decidim/api/docs" %>
+    <%= stylesheet_link_tag "decidim/api/docs" %>
+    <style>
+    </style>
   </head>
   <body>
     <%= yield %>

diff --git a/decidim-api/decidim-api.gemspec b/decidim-api/decidim-api.gemspec
@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
   s.add_dependency "graphiql-rails", "~> 1.4", "< 1.5"
   s.add_dependency "graphql", "~> 1.9"
   s.add_dependency "rack-cors", "~> 1.0"
+  s.add_dependency "redcarpet", "~> 3.4"
   s.add_dependency "sprockets-es6", "~> 0.9.2"
 
   s.add_development_dependency "decidim-comments", Decidim::Api.version