rspec-apidoc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70f813f8f9f45e4f454cd07147cc1ff8dc22496ddd99e22bccf098b6f513f732
-  data.tar.gz: a817bac7f9c2f5bed38117de7634ae16520192f9f4a3864e685016d6f5e5d283
+  metadata.gz: 8700f45112bb1c1a6a8ca9770020b00c5e1887e673e4353b305ecc66f89f5d70
+  data.tar.gz: 9ce1fb0139b48f53dce57b0f51728ddcbf58546b64c99105437dc9b637bdf5ee
 SHA512:
-  metadata.gz: c52748bb8d403685869114c402c36ee40ba0f1a3909871bc430cd753a4c74b626ad1d5f6252c5428d9ca628fe6757ae934ebbce923c9231e31205c77b989c722
-  data.tar.gz: b2f2f1f893a876532f404ecd47598e986f805b888503055668ed7144f2f972a45ef4783fb12df76602107adbdce9b6ef05338bb1321fb3195d6fa7cb231e655c
+  metadata.gz: 617d0a747bb1977de943ec794fde2c4975bc5058d93c5e6cdd1ae88a8075e24c20db6b187b3d8fb59661961974555305c50ace0558662697103bb60c3feab20c
+  data.tar.gz: 0c82c4f051092f3517279e1c5d4ca0cd4e7eaae8471dfe81b8240bad3517d0d023965e129cf0fb169d6df5b372cd23d7fa8d8b4b88f695ccceef35a85b1bac2e

data/README.md

@@ -47,12 +47,17 @@ RSpec.configure do |config|
 
   config.apidoc_title = 'YOUR.APP API Documentation'
   config.apidoc_description = \
-    'A longer intro to add before the examples: authtication, status codes...'
+    'A longer intro to add before the examples: authentication, status codes...'
 
   config.apidoc_host = 'https://api.YOUR.APP'
   # Optionally specify the output file path.
   config.apidoc_output_filename = 'apidoc.html'
 
+  # Customize the authentication header
+  config.apidoc_auth_header = lambda do |headers|
+    '"Authorization: Bearer $AUTH_TOKEN"' if headers['Authorization']
+  end
+
   # You can add it to any example based on the metadata.
   config.after(:each, type: :request) do |example|
     RSpec::Apidoc.add(self, example)

data/lib/rspec/apidoc/static/template.html.erb

@@ -90,10 +90,14 @@
         </div>
 
         <% examples.each do |controller, items| %>
-          <% items.sort.each do |action, action_items| %>
+          <% items.sort.each_with_index do |(action, action_items), mindex| %>
             <% action_items.each_with_index do |item, index| %>
-              <div class="example">
-                <% if index == 0 %>
+              <div class="example" id="<%= controller %>-<%= action %>-<%= mindex + index %>">
+                <% if mindex == 0 %>
+                  <%= item[:controller_comment] %>
+                <% end %>
+
+                <% if mindex == 0 && index == 0 %>
                   <div class="example-doc" id="<%= controller %>-<%= action %>">
                     <%= item[:action_comment] || ( item[:method] + ' ' + controller ) %>
                   </div>
@@ -104,11 +108,20 @@
                   <div class="request">
                     <span>Request</span>
                     <pre>
-$ curl '<%= host %><%= item[:path] %><%= ('?' + item[:query]) if item[:query] != '' %>' \
-  -X <%= item[:method] %> \
-  -H 'Content-Type: <%= item[:content_type] %>' <% if item[:request_body] != '' %> \
-  @- &lt;&lt; EOF
+$ curl -X <%= item[:method] %> '<%= host %><%= item[:path] %><%= ('?' + item[:query]) if item[:query] != '' %>' \
+<%- if item[:auth_header] -%>
+  -H <%= item[:auth_header] %> <%- if item[:content_type] %>\<% end %>
+<%- end -%>
+<%- if item[:content_type] -%>
+  -H 'Content-Type: <%= item[:content_type] %>'  <%- if item[:request_body] %>\<% end %>
+<%- end -%>
+<%- if item[:request_body] != '' -%>
+  -d - &lt;&lt; EOF
+<% if item[:request_body].is_a?(String) -%>
+<%=h item[:request_body] -%>
+<% else %>
 <%=h JSON.pretty_generate(item[:request_body]) %>
+<%- end %>
 EOF
         <% end %>
                     </pre>
@@ -116,9 +129,14 @@ EOF
                   <div class="response">
                     <span>Response</span>
                     <pre>
-&lt; Content-Type: <%= item[:response_content_type] %>
+&lt; Content-Type: <%= item[:response_content_type] -%>
 &lt; Status: <%= item[:status] %>
-<%=h JSON.pretty_generate(item[:response_body]) %>
+
+<% if item[:response_body].is_a?(String) -%>
+<%=h item[:response_body] -%>
+<% else %>
+<%=h JSON.pretty_generate(item[:response_body]) -%>
+<%- end -%>
                     </pre>
                   </div>
                 </div>
@@ -135,6 +153,9 @@ EOF
     </div>
     <div class="footer">
       &copy; <%= Date.current.year %> <%= title %>
+      <p>
+        <small>Latest update at <%= DateTime.current.to_s %></small>
+      </p>
     </div>
   </body>
 </html>

data/lib/rspec/apidoc.rb

@@ -13,6 +13,7 @@ module RSpec
     config.add_setting(:apidoc_title)
     config.add_setting(:apidoc_description)
     config.add_setting(:apidoc_host)
+    config.add_setting(:apidoc_auth_header, default: ->(headers) {})
     config.add_setting(
       :apidoc_template_path,
       default: File.expand_path('apidoc/static/template.html.erb', __dir__)
@@ -65,6 +66,14 @@ module RSpec
       RSpec.configuration.apidoc_host
     end
 
+    # Returns the API authentication header callback result
+    #
+    # @param headers [ActionDispatch::Http::Headers] object
+    # @return [Object]
+    def self.auth_header(headers)
+      RSpec.configuration.apidoc_auth_header.call(headers)
+    end
+
     # Returns the collected examples, sorted
     #
     # @return [Array] a list of [Hash] items
@@ -82,15 +91,22 @@ module RSpec
       response_body = parse_json_safely(spec.response.body)
 
       if spec.request.controller_instance
-        action_comment = spec.request.controller_class.instance_method(
-          spec.request.controller_instance.action_name
-        ).comment
+        action_name = spec.request.controller_instance.action_name
+        action_method = spec.request.controller_instance.method(action_name)
         # Remove any `@param` or `@return` lines
-        action_comment = action_comment.delete('#').gsub(/@.*$/, '').strip
+        action_comment = action_method.comment
+          .gsub(/^#(\s+)?$/, "\n").gsub(/^#(\s+)?/, '').gsub(/^@.*$/, '')
         controller_class = spec.request.controller_class
-        action_name = spec.request.controller_instance.action_name
+        controller_comment = nil
+
+        if action_method.respond_to?(:class_comment)
+          controller_comment = action_method.class_comment.gsub(
+            /.*frozen_string_literal:.*/, ''
+          ).gsub(/^#(\s+)?$/, "\n").gsub(/^#(\s+)?/, '').gsub(/^@.*$/, '')
+        end
       else
         action_comment = nil
+        controller_comment = nil
         controller_class = spec.request.path
         action_name = spec.request.method
       end
@@ -99,10 +115,12 @@ module RSpec
         description: example.metadata[:full_description],
 
         controller_class: controller_class,
+        controller_comment: controller_comment,
         action_name: action_name,
         action_comment: action_comment,
 
         content_type: spec.request.content_type,
+        auth_header: auth_header(spec.request.headers),
         method: spec.request.method,
         path: spec.request.path,
         query: spec.request.query_parameters.to_param,
@@ -145,7 +163,7 @@ module RSpec
     def close(_notification)
       return if examples.empty?
 
-      erb = ERB.new(File.read(template_path))
+      erb = ERB.new(File.read(template_path), trim_mode: '-')
       File.write(output_filename, erb.result(self.binding))
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-apidoc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Stas Suscov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-02 00:00:00.000000000 Z
+date: 2021-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: method_source