Merge pull request #281 from jamietanna/defect/openapi

Fix: Don't break TOC when OpenAPI description includes headers

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Fixes
+
+- [#281: Fix: Don't break TOC when OpenAPI description includes headers](https://github.com/alphagov/tech-docs-gem/pull/281) - Thanks [@jamietanna](https://github.com/jamietanna)!
+
 ## 3.0.0
 
 ### Breaking changes

lib/govuk_tech_docs/api_reference/api_reference_renderer.rb

@@ -7,6 +7,7 @@ class Renderer
       def initialize(app, document)
         @app = app
         @document = document
+        @redcarpet = build_redcarpet(app)
 
         # Load template files
         @template_api_full = get_renderer("api_reference_full.html.erb")
@@ -137,6 +138,11 @@ def schema_properties(schema_data)
 
     private
 
+      def build_redcarpet(app)
+        renderer = GovukTechDocs::TechDocsHTMLRenderer.new(context: app.config_context)
+        Redcarpet::Markdown.new(renderer)
+      end
+
       def get_renderer(file)
         template_path = File.join(File.dirname(__FILE__), "templates/" + file)
         template = File.open(template_path, "r").read
@@ -159,6 +165,10 @@ def get_schema_link(schema)
         id = "schema-#{schema.name.parameterize}"
         "<a href='\##{id}'>#{schema.name}</a>"
       end
+
+      def render_markdown(text)
+        @redcarpet.render(text) if text
+      end
     end
   end
 end

lib/govuk_tech_docs/api_reference/templates/api_reference_full.html.erb

@@ -1,13 +1,13 @@
 <h1 id="<%=  info.title.parameterize %>"><%= info.title %> v<%= info.version %></h1>
-<%= info.description_html %>
+<%= render_markdown(info.description) %>
 
 <%# OpenAPI files default to having a single server of URL "/" %>
 <% if servers.length > 1 || servers[0].url != "/" %>
   <h2 id="servers">Servers</h2>
   <div id="server-list">
     <% servers.each do |server| %>
     <% if server.description %>
-    <p><strong><%= server.description %></strong></p>
+    <p><strong><%= render_markdown(server.description) %></strong></p>
     <% end %>
     <a href="<%= server.url %>"><%= server.url %></a>
   <% end %>

lib/govuk_tech_docs/api_reference/templates/operation.html.erb

@@ -3,7 +3,7 @@
   <p><em><%= operation.summary %></em></p>
 <% end %>
 <% if operation.description %>
-  <%= operation.description_html %>
+  <%= render_markdown(operation.description) %>
 <% end %>
 
 <%= parameters %>

lib/govuk_tech_docs/api_reference/templates/parameters.html.erb

@@ -11,7 +11,7 @@
 <td><%= parameter.in %></td>
 <td><%= parameter.schema.type %></td>
 <td><%= parameter.required? %></td>
-<td><%= parameter.description_html %>
+<td><%= render_markdown(parameter.description) %>
 <% if parameter.schema.enum %>
 <p>Available items:</p>
 <ul>

lib/govuk_tech_docs/api_reference/templates/responses.html.erb

@@ -9,7 +9,7 @@
 <tr>
 <td><%= key %></td>
 <td>
-<%= response.description_html %>
+<%= render_markdown(response.description) %>
 <% if response.content['application/json']
 if response.content['application/json']["example"]
   request_body = json_prettyprint(response.content['application/json']["example"])

lib/govuk_tech_docs/api_reference/templates/schema.html.erb

@@ -1,5 +1,5 @@
 <h3 id="<%= id = 'schema-' + title; id.parameterize %>"><%= title %></h3>
-<%= schema.description_html %>
+<%= render_markdown(schema.description) %>
 <% if properties.any? %>
 <table class='<%= id.parameterize %>'>
 <thead>
@@ -11,7 +11,7 @@
 <td><%= property_name %></td>
 <td><%= property_attributes.type %></td>
 <td><%= schema.requires?(property_name) %></td>
-<td><%= property_attributes.description_html %></td>
+<td><%= render_markdown(property_attributes.description) %></td>
 <td>
   <%=
   linked_schema = property_attributes

spec/api_reference/renderer_spec.rb

@@ -11,15 +11,34 @@
         "info": {
           "title": "title",
           "version": "0.0.1",
+          "description": "# This is a header\n\nAnd a piece of _text_",
         },
         "paths": {},
       }
+      @app = double("Middleman::Application")
+      @config_context = double("Middleman::ConfigContext")
+      allow(@app).to receive(:config_context).and_return @config_context
+      allow(@config_context).to receive(:app).and_return @app
+      allow(@app).to receive(:api) { |arg| arg }
+    end
+
+    it "renders the description" do
+      document = Openapi3Parser.load(@spec)
+
+      render = described_class.new(@app, document)
+      rendered = render.api_full(document.info, document.servers)
+
+      rendered = Capybara::Node::Simple.new(rendered)
+      expect(rendered).to have_css("h1", exact_text: "This is a header")
+      expect(rendered).to have_css("h1#this-is-a-header")
+      expect(rendered).to have_css("p", exact_text: "And a piece of text")
+      expect(rendered).to have_css("p>em", exact_text: "text")
     end
 
     it "renders no servers" do
       document = Openapi3Parser.load(@spec)
 
-      render = described_class.new(nil, document)
+      render = described_class.new(@app, document)
       rendered = render.api_full(document.info, document.servers)
 
       rendered = Capybara::Node::Simple.new(rendered)
@@ -33,7 +52,7 @@
       ]
       document = Openapi3Parser.load(@spec)
 
-      render = described_class.new(nil, document)
+      render = described_class.new(@app, document)
       rendered = render.api_full(document.info, document.servers)
 
       rendered = Capybara::Node::Simple.new(rendered)
@@ -45,11 +64,11 @@
     it "renders a list of servers" do
       @spec["servers"] = [
         { "url": "https://example.com", "description": "Production" },
-        { "url": "https://dev.example.com", "description": "Development" },
+        { "url": "https://dev.example.com", "description": "_Development_" },
       ]
       document = Openapi3Parser.load(@spec)
 
-      render = described_class.new(nil, document)
+      render = described_class.new(@app, document)
       rendered = render.api_full(document.info, document.servers)
 
       rendered = Capybara::Node::Simple.new(rendered)
@@ -58,6 +77,7 @@
       expect(rendered).to have_css("div#server-list>p>strong", text: "Production")
       expect(rendered).to have_css("div#server-list>a", text: "https://dev.example.com")
       expect(rendered).to have_css("div#server-list>p>strong", text: "Development")
+      expect(rendered).to have_css("div#server-list>p>strong>p>em", text: "Development")
     end
   end
 end