rspec-apidoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 70f813f8f9f45e4f454cd07147cc1ff8dc22496ddd99e22bccf098b6f513f732
+  data.tar.gz: a817bac7f9c2f5bed38117de7634ae16520192f9f4a3864e685016d6f5e5d283
+SHA512:
+  metadata.gz: c52748bb8d403685869114c402c36ee40ba0f1a3909871bc430cd753a4c74b626ad1d5f6252c5428d9ca628fe6757ae934ebbce923c9231e31205c77b989c722
+  data.tar.gz: b2f2f1f893a876532f404ecd47598e986f805b888503055668ed7144f2f972a45ef4783fb12df76602107adbdce9b6ef05338bb1321fb3195d6fa7cb231e655c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Stas Suscov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+# RSpec HTTP API Documentation 📠
+
+Automatically generates the documentation for your HTTP API.
+
+The idea is simple, you write the request specs, run your tests and you end
+up with an HTML file with grouped examples of the request and response
+examples.
+
+## But why?
+
+I've tried a lot of tools in the hope to solve a simple problem: automatically
+generate the API documentation based on a simple RSpec request test.
+
+Tools like Blueprint, OpenAPI Swagger are great as a concept, but either
+require some DSL (aka, more work on my side huh) or these are high maintenance
+if your API design requires some flexibility and rapidly evolves.
+
+Either way, there's only one single source of truth: **your tested code**.
+This tool is just an easy way to help your front-end/mobile team how to
+communicate with your HTTP API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rspec-apidoc'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rspec-apidoc
+
+## Usage
+
+Add this to your RSpec setup (eg. `spec/support/autoapi.rb`):
+
+```ruby
+RSpec.configure do |config|
+  config.add_formatter(RSpec::Apidoc)
+  # Optionally add a visual formatter as well...
+  # config.add_formatter(:progress)
+
+  config.apidoc_title = 'YOUR.APP API Documentation'
+  config.apidoc_description = \
+    'A longer intro to add before the examples: authtication, status codes...'
+
+  config.apidoc_host = 'https://api.YOUR.APP'
+  # Optionally specify the output file path.
+  config.apidoc_output_filename = 'apidoc.html'
+
+  # You can add it to any example based on the metadata.
+  config.after(:each, type: :request) do |example|
+    RSpec::Apidoc.add(self, example)
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle` to install dependencies.
+
+Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update the version number in `version.rb`, and then
+run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting with this project codebase, issue
+tracker, chat rooms and mailing list is expected to follow the [code of
+conduct](https://github.com/[USERNAME]/active_record-pgcrypto/blob/master/CODE_OF_CONDUCT.md).

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

@@ -0,0 +1,140 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title><%= title %></title>
+    <style>
+      html { font-family: sans-serif; }
+      .header {
+        border-bottom: 1px solid #EEE;
+        padding: 30px;
+        text-transform: uppercase;
+        font-size: 250%;
+        font-weight: bold;
+      }
+      .footer { padding: 60px; border-top: 1px solid #EEE; color: #CCC; }
+      #examples { display: flex; }
+      #toc {
+        border-right: 1px solid #EEE;
+        text-transform: uppercase;
+        max-width: 30%;
+      }
+      #toc ul { list-style-type:none; margin: 0; padding: 0; }
+      #toc li a, #toc li span {
+        display: block;
+        padding: 30px;
+        border-bottom: 1px solid #EEE;
+      }
+      #toc li span { font-weight: bold; color: #555; }
+      #docs { width: 100%; max-width: 70%; }
+      pre {
+        background: #444;
+        color: #CCC;
+        padding: 20px;
+        margin-top: 0;
+        white-space: pre-wrap;
+        overflow: auto;
+      }
+      .example-doc {
+        border-bottom: 1px solid #DDD;
+        padding-bottom: 30px;
+        margin-bottom: 30px;
+      }
+      .example { padding: 30px 60px; }
+      .example:nth-child(even) { background: #EEE; }
+      .request-response { display: flex; justify-content: space-between; }
+      .request, .response { width: 45%; }
+      .request span, .response span {
+        padding: 10px;
+        background: #CCC;
+        color: #333;
+        font-weight: bold;
+        border-radius: 10px 10px 0 0;
+        text-transform: uppercase;
+        font-size: 70%;
+        display: block;
+      }
+      .arrow-up { font-weight: bold; font-size: 150%; }
+    </style>
+  </head>
+  <body>
+    <div class="header">
+      <span><%= title %></span>
+    </div>
+
+    <div id="examples">
+      <div id="toc">
+        <ul>
+          <li><a href="#examples">Home</a></li>
+          <% examples.each do |controller, items| %>
+            <li>
+              <span><%= controller %></span>
+              <ul>
+                <% items.keys.sort.each do |action| %>
+                  <li>
+                    <a href="#<%= controller %>-<%= action %>">
+                      <%= action %>
+                    </a>
+                  </li>
+                <% end %>
+              </ul>
+            </li>
+          <% end %>
+        </ul>
+      </div>
+
+      <div id="docs">
+        <div class="example">
+          <h1><%= title %></h1>
+          <%= description %>
+        </div>
+
+        <% examples.each do |controller, items| %>
+          <% items.sort.each do |action, action_items| %>
+            <% action_items.each_with_index do |item, index| %>
+              <div class="example">
+                <% if index == 0 %>
+                  <div class="example-doc" id="<%= controller %>-<%= action %>">
+                    <%= item[:action_comment] || ( item[:method] + ' ' + controller ) %>
+                  </div>
+                <% end %>
+
+                <p><%= item[:description] %></>
+                <div class="request-response">
+                  <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
+<%=h JSON.pretty_generate(item[:request_body]) %>
+EOF
+        <% end %>
+                    </pre>
+                  </div>
+                  <div class="response">
+                    <span>Response</span>
+                    <pre>
+&lt; Content-Type: <%= item[:response_content_type] %>
+&lt; Status: <%= item[:status] %>
+<%=h JSON.pretty_generate(item[:response_body]) %>
+                    </pre>
+                  </div>
+                </div>
+
+                <p>
+                  <a class=".arrow-up" href="#examples">&#11205;</a>
+                </p>
+              </div>
+
+            <% end %>
+          <% end %>
+        <% end %>
+      </div>
+    </div>
+    <div class="footer">
+      &copy; <%= Date.current.year %> <%= title %>
+    </div>
+  </body>
+</html>

data/lib/rspec/apidoc.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'rspec/core/formatters/base_formatter'
+require 'method_source'
+require 'erb'
+
+# rubocop:disable Style/Documentation
+module RSpec
+  # rubocop:enable Style/Documentation
+
+  # Add our settings...
+  configure do |config|
+    config.add_setting(:apidoc_title)
+    config.add_setting(:apidoc_description)
+    config.add_setting(:apidoc_host)
+    config.add_setting(
+      :apidoc_template_path,
+      default: File.expand_path('apidoc/static/template.html.erb', __dir__)
+    )
+    config.add_setting(:apidoc_output_filename, default: 'apidoc.html')
+  end
+
+  # Our formatter class.
+  #
+  # We're using the formatter as the hooks do not allow to report when the
+  # test runner is done.
+  class Apidoc < RSpec::Core::Formatters::BaseFormatter
+    include ERB::Util
+
+    # We want only passed tests registered and know when the runner is finished
+    RSpec::Core::Formatters.register self, :example_passed, :close
+
+    # Returns the title for our docs
+    #
+    # @return [String]
+    def title
+      RSpec.configuration.apidoc_title
+    end
+
+    # Returns the description for our docs
+    #
+    # @return [String]
+    def description
+      RSpec.configuration.apidoc_description
+    end
+
+    # Returns the template path used to render our docs
+    #
+    # @return [String]
+    def template_path
+      RSpec.configuration.apidoc_template_path
+    end
+
+    # Returns the final document path for our docs
+    #
+    # @return [String]
+    def output_filename
+      RSpec.configuration.apidoc_output_filename
+    end
+
+    # Returns the API host used to generate the `curl` commands
+    #
+    # @return [String]
+    def host
+      RSpec.configuration.apidoc_host
+    end
+
+    # Returns the collected examples, sorted
+    #
+    # @return [Array] a list of [Hash] items
+    def examples
+      @examples ||= {}
+      @examples = @examples.sort.to_h
+    end
+
+    # Parses and stores relevant to our docs data in the example metadata
+    #
+    # @return [Hash] the metadata that was added
+    # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+    def self.add(spec, example)
+      request_body = parse_json_safely(spec.request.body.string)
+      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
+        # Remove any `@param` or `@return` lines
+        action_comment = action_comment.delete('#').gsub(/@.*$/, '').strip
+        controller_class = spec.request.controller_class
+        action_name = spec.request.controller_instance.action_name
+      else
+        action_comment = nil
+        controller_class = spec.request.path
+        action_name = spec.request.method
+      end
+
+      example.metadata[:apidoc_data] = {
+        description: example.metadata[:full_description],
+
+        controller_class: controller_class,
+        action_name: action_name,
+        action_comment: action_comment,
+
+        content_type: spec.request.content_type,
+        method: spec.request.method,
+        path: spec.request.path,
+        query: spec.request.query_parameters.to_param,
+        request_body: request_body,
+
+        status: spec.response.status,
+        response_content_type: spec.response.content_type,
+        response_body: response_body
+      }
+    end
+    # rubocop:enable Metrics/AbcSize,Metrics/MethodLength
+
+    # Returns a parsed JSON object
+    #
+    # @param obj [Object] an object to parse as JSON
+    # @return [Object]
+    def self.parse_json_safely(obj)
+      JSON.parse(obj)
+    rescue StandardError
+      obj.to_s
+    end
+
+    # Formatter callback, stores the example metadata for later to be used
+    #
+    # @return [Hash] the metadata that was stored
+    def example_passed(notification)
+      apidoc_data = notification.example.metadata[:apidoc_data]
+
+      return if apidoc_data.nil?
+
+      controller_name = apidoc_data[:controller_class].to_s
+      controller_examples = examples[controller_name] ||= {}
+      controller_examples[apidoc_data[:action_name]] ||= []
+      controller_examples[apidoc_data[:action_name]].append(apidoc_data)
+    end
+
+    # Formatter callback, generates the HTML from the metadata we stored
+    #
+    # @return [Integer] size of the new file.
+    def close(_notification)
+      return if examples.empty?
+
+      erb = ERB.new(File.read(template_path))
+      File.write(output_filename, erb.result(self.binding))
+    end
+  end
+end

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: rspec-apidoc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stas Suscov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Automatically generates the documentation for your HTTP API.
+email:
+- stas@nerd.ro
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rspec/apidoc.rb
+- lib/rspec/apidoc/static/template.html.erb
+homepage: https://github.com/HeyBetter/rspec-apidoc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/HeyBetter/rspec-apidoc
+  source_code_uri: https://github.com/HeyBetter/rspec-apidoc
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: RSpec HTTP API Documentation
+test_files: []