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

lazy_api_doc 0.1.6 → 0.2.2

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