RubyGems - lazy_api_doc - Versions diffs - 0.1.6 → 0.2.2 - Mend

lazy_api_doc 0.1.6 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

checksums.yaml +4 -4
data/Gemfile.lock +1 -1
data/README.md +22 -3
data/docs/example/api.yml +1355 -0
data/docs/example/index.html +24 -0
data/docs/example/layout.yml +14 -0
data/lib/generators/lazy_api_doc/install_generator.rb +42 -14
data/lib/lazy_api_doc/generator.rb +22 -15
data/lib/lazy_api_doc/route_parser.rb +6 -6
data/lib/lazy_api_doc/variants_parser.rb +2 -2
data/lib/lazy_api_doc/version.rb +1 -1
data/lib/lazy_api_doc.rb +92 -51
data/screenshot.png +0 -0
metadata +6 -2

data/docs/example/index.html ADDED Viewed

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Application Documentation</title>
+  <!-- needed for adaptive design -->
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+  <!--
+  ReDoc doesn't change outer page styles
+  -->
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+<body>
+<redoc spec-url='./api.yml'></redoc>
+<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
+</body>
+</html>

data/docs/example/layout.yml ADDED Viewed

@@ -0,0 +1,14 @@
+openapi: 3.0.0
+info:
+  title: App name
+  version: "1.0.0"
+  contact:
+    name: User Name
+    email: user@example.com
+    url: https://app.example.com
+servers:
+  - url: https://app.example.com
+    description: description
+paths:

data/lib/generators/lazy_api_doc/install_generator.rb CHANGED Viewed

@@ -1,4 +1,5 @@
 require 'rails/generators'
+require 'lazy_api_doc'
 module LazyApiDoc
   module Generators
@@ -7,8 +8,17 @@ module LazyApiDoc
       desc "Copy base configuration for LazyApiDoc"
       def install
-        copy_file 'public/index.html', 'public/lazy_api_doc/index.html'
-        copy_file 'public/layout.yml', 'public/lazy_api_doc/layout.yml'
+        copy_file 'public/index.html', "#{LazyApiDoc.path}/index.html"
+        copy_file 'public/layout.yml', "#{LazyApiDoc.path}/layout.yml"
+        append_to_file '.gitignore' do
+          <<~TXT
+          # LazyApiDoc
+          #{LazyApiDoc.path}/api.yml
+          #{LazyApiDoc.path}/examples/*.json
+          TXT
+        end
         install_rspec if Dir.exist?('spec')
@@ -21,18 +31,27 @@ module LazyApiDoc
         copy_file 'support/rspec_interceptor.rb', 'spec/support/lazy_api_doc_interceptor.rb'
         insert_into_file 'spec/rails_helper.rb', after: "RSpec.configure do |config|\n" do
-          <<~RUBY
-            if ENV['DOC']
-              require 'lazy_api_doc'
-              require 'support/lazy_api_doc_interceptor'
+          <<-RUBY
+  if ENV['LAZY_API_DOC']
+    require 'lazy_api_doc'
+    require 'support/lazy_api_doc_interceptor'
-              config.include LazyApiDocInterceptor, type: :request
-              config.include LazyApiDocInterceptor, type: :controller
+    config.include LazyApiDocInterceptor, type: :request
+    config.include LazyApiDocInterceptor, type: :controller
-              config.after(:suite) do
-                LazyApiDoc.save_result
-              end
-            end
+    config.after(:suite) do
+      # begin: Handle ParallelTests
+      # This peace of code handle using ParallelTests (tests runs in independent processes).
+      # Just delete this block if you don't use ParallelTests
+      if ENV['TEST_ENV_NUMBER'] && defined?(ParallelTests)
+        LazyApiDoc.save_examples('rspec')
+        ParallelTests.wait_for_other_processes_to_finish if ParallelTests.first_process?
+        LazyApiDoc.load_examples
+      end
+      # end: Handle ParallelTests
+      LazyApiDoc.generate_documentation
+    end
+  end
           RUBY
         end
       end
@@ -43,7 +62,7 @@ module LazyApiDoc
         append_to_file 'test/test_helper.rb' do
           <<~RUBY
-            if ENV['DOC']
+            if ENV['LAZY_API_DOC']
               require 'lazy_api_doc'
               require 'support/lazy_api_doc_interceptor'
@@ -52,7 +71,16 @@ module LazyApiDoc
               end
               Minitest.after_run do
-                LazyApiDoc.save_result
+                # begin: Handle ParallelTests
+                # This peace of code handle using ParallelTests (tests runs in independent processes).
+                # Just delete this block if you don't use ParallelTests
+                if ENV['TEST_ENV_NUMBER'] && defined?(ParallelTests)
+                  LazyApiDoc.save_examples('minitest')
+                  ParallelTests.wait_for_other_processes_to_finish if ParallelTests.first_process?
+                  LazyApiDoc.load_examples
+                end
+                # end: Handle ParallelTests
+                LazyApiDoc.generate_documentation
               end
             end
           RUBY

data/lib/lazy_api_doc/generator.rb CHANGED Viewed

@@ -9,24 +9,33 @@ module LazyApiDoc
     end
     def add(example)
-      return if example[:controller] == "anonymous" # don't handle virtual controllers
+      return if example['controller'] == "anonymous" # don't handle virtual controllers
       @examples << example
     end
+    def clear
+      @examples = []
+    end
     def result
       result = {}
       @examples.map { |example| OpenStruct.new(example) }.sort_by(&:source_location)
-               .group_by { |ex| [ex.controller, ex.action] }.map do |_, examples|
+               .group_by { |ex| [ex.controller, ex.action] }
+               .each do |_, examples|
         first = examples.first
         route = ::LazyApiDoc::RouteParser.new(first.controller, first.action, first.verb).route
-        doc_path = route[:doc_path]
+        next if route.nil? # TODO: think about adding such cases to log
+        doc_path = route['doc_path']
         result[doc_path] ||= {}
         result[doc_path].merge!(example_group(first, examples, route))
       end
       result
     end
+    private
     def example_group(example, examples, route) # rubocop:disable Metrics/AbcSize
       {
         example['verb'].downcase => {
@@ -35,13 +44,13 @@ module LazyApiDoc
           "summary" => example.action,
           "parameters" => path_params(route, examples) + query_params(examples),
           "requestBody" => body_params(route, examples),
-          "responses" => examples.group_by { |ex| ex.response[:code] }.map do |code, variants|
+          "responses" => examples.group_by { |ex| ex.response['code'] }.map do |code, variants|
             [
               code,
               {
                 "description" => variants.first["description"].capitalize,
                 "content" => {
-                  example.response[:content_type] => {
+                  example.response['content_type'] => {
                     "schema" => ::LazyApiDoc::VariantsParser.new(variants.map { |v| parse_body(v.response) }).result
                   }
                 }
@@ -53,17 +62,17 @@ module LazyApiDoc
     end
     def parse_body(response)
-      if response[:content_type].match?("json")
-        JSON.parse(response[:body])
+      if response['content_type'].match?("json")
+        JSON.parse(response['body'])
       else
         "Not a JSON response"
       end
     rescue JSON::ParserError
-      response[:body]
+      response['body']
     end
     def path_params(route, examples)
-      path_variants = examples.map { |example| example.params.slice(*route[:path_params]) }
+      path_variants = examples.map { |example| example.params.slice(*route['path_params']) }
       ::LazyApiDoc::VariantsParser.new(path_variants).result["properties"].map do |param_name, schema|
         {
           'in' => "path",
@@ -76,12 +85,10 @@ module LazyApiDoc
     def query_params(examples)
       query_variants = examples.map do |example|
-        full_path = example.request[:full_path].split('?')
-        next {} if full_path.size == 1
+        _path, query = example.request['full_path'].split('?')
+        next {} unless query
-        # TODO: simplify it
-        full_path.last.split('&').map { |part| part.split('=').map { |each| CGI.unescape(each) } }.group_by(&:first)
-                 .transform_values { |v| v.map(&:last) }.map { |k, v| [k, k.match?(/\[\]\z/) ? v : v.first] }.to_h
+        CGI.parse(query).map { |k, v| [k.gsub('[]', ''), k.match?('\[\]') ? v : v.first] }.to_h
       end
       parsed = ::LazyApiDoc::VariantsParser.new(query_variants).result
@@ -99,7 +106,7 @@ module LazyApiDoc
       first = examples.first
       return unless %w[POST PATCH].include?(first['verb'])
-      variants = examples.map { |example| example.params.except("controller", "action", *route[:path_params]) }
+      variants = examples.map { |example| example.params.except("controller", "action", "format", *route['path_params']) }
       {
         'content' => {
           first.content_type => {

data/lib/lazy_api_doc/route_parser.rb CHANGED Viewed

@@ -9,7 +9,7 @@ module LazyApiDoc
     end
     def route
-      self.class.routes.find { |r| r[:action] == action && r[:controller] == controller && r[:verb].include?(verb) }
+      self.class.routes.find { |r| r['action'] == action && r['controller'] == controller && r['verb'].include?(verb) }
     end
     def self.routes
@@ -22,11 +22,11 @@ module LazyApiDoc
       route = ActionDispatch::Routing::RouteWrapper.new(route)
       {
-        doc_path: route.path.gsub("(.:format)", "").gsub(/(:\w+)/, '{\1}').delete(":"),
-        path_params: route.path.gsub("(.:format)", "").scan(/:\w+/).map { |p| p.delete(":").to_sym },
-        controller: route.controller,
-        action: route.action,
-        verb: route.verb.split('|')
+        'doc_path' => route.path.gsub("(.:format)", "").gsub(/(:\w+)/, '{\1}').delete(":"),
+        'path_params' => route.path.gsub("(.:format)", "").scan(/:\w+/).map { |p| p.delete(":") },
+        'controller' => route.controller,
+        'action' => route.action,
+        'verb' => route.verb.split('|')
       }
     end
   end

data/lib/lazy_api_doc/variants_parser.rb CHANGED Viewed

@@ -73,10 +73,10 @@ module LazyApiDoc
       result["properties"] = variant.map do |key, val|
         [
           key.to_s,
-          parse(val, variants.compact.map { |v| v.fetch(key, OPTIONAL) })
+          parse(val, variants.select { |v| v.is_a?(Hash) }.map { |v| v.fetch(key, OPTIONAL) })
         ]
       end.to_h
-      result["required"] = variant.keys.select { |key| variants.compact.all? { |v| v.key?(key) } }
+      result["required"] = variant.keys.select { |key| variants.select { |v| v.is_a?(Hash) }.all? { |v| v.key?(key) } }
       result
     end

data/lib/lazy_api_doc/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module LazyApiDoc
-  VERSION = "0.1.6".freeze
+  VERSION = "0.2.2".freeze
 end

data/lib/lazy_api_doc.rb CHANGED Viewed

@@ -7,60 +7,101 @@ require "yaml"
 module LazyApiDoc
   class Error < StandardError; end
-  def self.generator
-    @generator ||= Generator.new
-  end
+  class << self
+    attr_accessor :path, :example_file_ttl
-  def self.add(example)
-    generator.add(example)
-  end
+    def configure
+      yield self
+    end
-  def self.add_spec(example) # rubocop:disable Metrics/AbcSize
-    add(
-      controller: example.request.params[:controller],
-      action: example.request.params[:action],
-      description: example.class.description,
-      source_location: [example.class.metadata[:file_path], example.class.metadata[:line_number]],
-      verb: example.request.method,
-      params: example.request.params,
-      content_type: example.request.content_type.to_s,
-      request: {
-        query_params: example.request.query_parameters,
-        full_path: example.request.fullpath
-      },
-      response: {
-        code: example.response.status,
-        content_type: example.response.content_type.to_s,
-        body: example.response.body
-      }
-    )
-  end
+    def reset!
+      config_file = './config/lazy_api_doc.yml'
+      config = File.exist?(config_file) ? YAML.safe_load(ERB.new(File.read(config_file)).result) : {}
-  def self.add_test(example) # rubocop:disable Metrics/AbcSize
-    add(
-      controller: example.request.params[:controller],
-      action: example.request.params[:action],
-      description: example.name.gsub(/\Atest_/, '').humanize,
-      source_location: example.method(example.name).source_location,
-      verb: example.request.method,
-      params: example.request.params,
-      content_type: example.request.content_type.to_s,
-      request: {
-        query_params: example.request.query_parameters,
-        full_path: example.request.fullpath
-      },
-      response: {
-        code: example.response.status,
-        content_type: example.response.content_type.to_s,
-        body: example.response.body
-      }
-    )
-  end
+      self.path = ENV['LAZY_API_DOC_PATH'] || config['path'] || 'public/lazy_api_doc'
+      self.example_file_ttl = ENV['LAZY_API_DOC_EXAMPLE_FILE_TTL'] || config['example_file_ttl'] || 1800 # 30 minutes
+    end
+    def generator
+      @generator ||= Generator.new
+    end
+    def add(lazy_example)
+      generator.add(lazy_example)
+    end
-  def self.save_result(to: 'public/lazy_api_doc/api.yml', layout: 'public/lazy_api_doc/layout.yml')
-    layout = YAML.safe_load(File.read(Rails.root.join(layout)))
-    layout["paths"] ||= {}
-    layout["paths"].merge!(generator.result)
-    File.write(Rails.root.join(to), layout.to_yaml)
+    def add_spec(rspec_example) # rubocop:disable Metrics/AbcSize
+      add(
+        'controller' => rspec_example.instance_variable_get(:@request).params[:controller],
+        'action' => rspec_example.instance_variable_get(:@request).params[:action],
+        'description' => rspec_example.class.description,
+        'source_location' => [rspec_example.class.metadata[:file_path], rspec_example.class.metadata[:line_number]],
+        'verb' => rspec_example.instance_variable_get(:@request).method,
+        'params' => rspec_example.instance_variable_get(:@request).params,
+        'content_type' => rspec_example.instance_variable_get(:@request).content_type.to_s,
+        'request' => {
+          'query_params' => rspec_example.instance_variable_get(:@request).query_parameters,
+          'full_path' => rspec_example.instance_variable_get(:@request).fullpath
+        },
+        'response' => {
+          'code' => rspec_example.response.status,
+          'content_type' => rspec_example.response.content_type.to_s,
+          'body' => rspec_example.response.body
+        }
+      )
+    end
+    def add_test(mini_test_example) # rubocop:disable Metrics/AbcSize
+      add(
+        'controller' => mini_test_example.instance_variable_get(:@request).params[:controller],
+        'action' => mini_test_example.instance_variable_get(:@request).params[:action],
+        'description' => mini_test_example.name.gsub(/\Atest_/, '').humanize,
+        'source_location' => mini_test_example.method(mini_test_example.name).source_location,
+        'verb' => mini_test_example.instance_variable_get(:@request).method,
+        'params' => mini_test_example.instance_variable_get(:@request).params,
+        'content_type' => mini_test_example.instance_variable_get(:@request).content_type.to_s,
+        'request' => {
+          'query_params' => mini_test_example.instance_variable_get(:@request).query_parameters,
+          'full_path' => mini_test_example.instance_variable_get(:@request).fullpath
+        },
+        'response' => {
+          'code' => mini_test_example.response.status,
+          'content_type' => mini_test_example.response.content_type.to_s,
+          'body' => mini_test_example.response.body
+        }
+      )
+    end
+    def generate_documentation
+      layout = YAML.safe_load(File.read("#{path}/layout.yml"))
+      layout["paths"] ||= {}
+      layout["paths"].merge!(generator.result)
+      File.write("#{path}/api.yml", layout.to_yaml)
+    end
+    def save_examples(process_name)
+      FileUtils.mkdir("#{path}/examples") unless File.exist?("#{path}/examples")
+      File.write(
+        "#{path}/examples/#{process_name}_#{ENV['TEST_ENV_NUMBER'] || SecureRandom.uuid}.json",
+        {
+          created_at: Time.now.to_i,
+          examples: generator.examples
+        }.to_json
+      )
+    end
+    def load_examples
+      valid_time = Time.now.to_i - example_file_ttl
+      examples = Dir["#{path}/examples/*.json"].flat_map do |file|
+        meta = JSON.parse(File.read(file))
+        next [] if meta['created_at'] < valid_time # do not handle outdated files
+        meta['examples']
+      end
+      generator.clear
+      examples.each { |example| add(example) }
+    end
   end
 end
+LazyApiDoc.reset!

data/screenshot.png ADDED Viewed

Binary file

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lazy_api_doc
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.2
 platform: ruby
 authors:
 - Bogdan Guban
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-02-08 00:00:00.000000000 Z
+date: 2022-06-02 00:00:00.000000000 Z
 dependencies: []
 description: The gem collects all requests and responses from your request specs and
   generates documentationbased on it
@@ -32,6 +32,9 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/example/api.yml
+- docs/example/index.html
+- docs/example/layout.yml
 - lazy_api_doc.gemspec
 - lib/generators/lazy_api_doc/install_generator.rb
 - lib/generators/lazy_api_doc/templates/public/index.html
@@ -43,6 +46,7 @@ files:
 - lib/lazy_api_doc/route_parser.rb
 - lib/lazy_api_doc/variants_parser.rb
 - lib/lazy_api_doc/version.rb
+- screenshot.png
 homepage: https://github.com/bguban/lazy_api_doc
 licenses:
 - MIT