fictium 0.1.0

data/README.md

@@ -0,0 +1,108 @@
+# Fictium
+
+[![Build Status](https://travis-ci.org/Wolox/fictium.svg?branch=master)](https://travis-ci.org/Wolox/fictium) [![Maintainability](https://api.codeclimate.com/v1/badges/52afbf838f92fe260b6e/maintainability)](https://codeclimate.com/github/Wolox/fictium/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/52afbf838f92fe260b6e/test_coverage)](https://codeclimate.com/github/Wolox/fictium/test_coverage)
+
+This gem is a documentation helper. The goal of this gem is, by adding small modifications into your existing tests,
+you can then transform it into easy REST documentation.
+
+For the initial release, the support is focused explicitly on generating documentation from [RSpec](https://rspec.info/) tests, and generate an [OpenAPI](https://github.com/OAI/OpenAPI-Specification) [V3.0.2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) Document.
+
+Future versions may allow to export to other OpenAPI versions, or even API Bluepint formats.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fictium'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fictium
+
+## Usage
+
+Fictium is a Gem to generate documentation from your tests.
+Instead of you having to write entirely new tests, the goal of this gem is to provide easy to use,
+tags and annotations on your existing tests.
+
+Fictium is closely tied to RSpec and Rails, but it's developed in a way to support more testing suites or engines in future versions.
+
+The primary goal is for generating OpenAPI Documentation, but, just like with RSpec, future versions may provide other output types.
+
+[Check out the wiki too!](./wiki)
+
+
+### Common terminology of this gem
+
+Because this GEM is used to represent REST APIs, this gem, provides some common objects, which are used as a documentation naming scheme. They are independant from the actual documentation format, so each exporter should transform this abstract representation into the actual document representation.
+
+The base object, is de [Fictium::Document](./lib/fictoum/poros/fictium/document). This class represent your whole API.
+One is created when the testing starts.
+
+The document, then is divided in resources. The class [Fictium::Resource](./lib/fictoum/poros/fictium/resource) is the one dedicated to handle them. A resource is a Rest object, for example, Posts, Users or Tags.
+
+Each resource is sub divided in actions, [Fictium::Action](./lib/fictoum/poros/fictium/action). Actions are enpoints associated with a REST method.
+
+### Configuration
+
+This gem attemps to complete the documentation for you, so you don't have to constantly document it yourself.
+To configure how this gem completes your documentation, you have some configurations available [here](https://github.com/Wolox/fictium/wiki).
+
+
+### RSpec Integration
+
+Just `require 'fictium/rspec'` in your spec helper and your RSpec test will include everything you need to work in your environment.
+
+At any test of type: :controller, you can just add the following helpers:
+
+```rb
+describe PostsController do
+  describe action 'GET #index' do
+    describe example 'without errors' do
+        default_example # You can select an example to be marked as default in your action
+
+        before do
+            get :index
+        end
+
+        # ... your tests
+    end
+  end
+end
+```
+
+The idea, is that your controller has actions, and each actions has examples.
+You can, for now, check `spec/controllers` at this repository to
+
+You can deeply customize your endpoints using RSpec.
+Check out details [here](./wiki/RSpec-definitions).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fictium. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+This gem is developed by (Wolox)[https://wolox.com.ar].
+
+Maintainers: [Ramiro Rojo](https://github.com/holywyvern)
+Contributors: None (for now...)
+![Wolox](https://raw.githubusercontent.com/Wolox/press-kit/master/logos/logo_banner.png)
+
+## Code of Conduct
+
+Everyone interacting in the Fictium project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Wolox/fictium/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+Dir[File.join(__dir__, 'tasks', '**', '*.rb')].each do |f|
+  require f
+end
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'fictium'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/fictium.gemspec

@@ -0,0 +1,57 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fictium/version'
+
+Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
+  spec.name          = 'fictium'
+  spec.version       = Fictium::VERSION
+  spec.authors       = ['Ramiro Rojo']
+  spec.email         = ['ramiro.rojo@wolox.com.ar']
+
+  spec.summary       = 'A gem to generate documentation out of tests.'
+  spec.homepage      = 'https://github.com/Wolox/fictium'
+  spec.license       = 'MIT'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/Wolox/fictium'
+  spec.metadata['changelog_uri'] = 'https://github.com/Wolox/fictium/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.6.0'
+
+  spec.add_runtime_dependency 'activesupport',
+                              Fictium::RAILS_MIN_VERSION,
+                              Fictium::RAILS_MAX_VERSION
+
+  spec.add_runtime_dependency 'json-schema', '~> 2.8'
+  spec.add_runtime_dependency 'verbs', '~> 2.1.4'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+
+  spec.add_development_dependency 'byebug'
+
+  spec.add_development_dependency 'brakeman'
+
+  spec.add_development_dependency 'faker', '~> 2.6.0'
+
+  spec.add_development_dependency 'rails',
+                                  Fictium::RAILS_MIN_VERSION,
+                                  Fictium::RAILS_MAX_VERSION
+  spec.add_development_dependency 'rake', '~> 12.3.3'
+  spec.add_development_dependency 'rspec', '~> 3.9'
+  spec.add_development_dependency 'rspec-rails', '~> 3.9'
+  spec.add_development_dependency 'rubocop', '0.75'
+  spec.add_development_dependency 'rubocop-rails', '2.3.2'
+  spec.add_development_dependency 'rubocop-rspec', '1.36.0'
+  spec.add_development_dependency 'simplecov', '~> 0.17.0'
+end

data/lib/fictium/configurations/configuration.rb

@@ -0,0 +1,87 @@
+module Fictium
+  class Configuration
+    VOWEL = /[aeiou]/i.freeze
+    DEFAULT_IGNORED_HEADERS_GROUPS = %w[rack. action_dispatch. action_controller.].freeze
+    DEFAULT_IGNORED_HEADERS = %w[
+      accept content-type authorization http_accept content_type
+      request_method server_name server_port query_string
+      http_cookie path_info x-frame-options x-xss-protection x-content-type-options
+      x-download-options x-permitted-cross-domain-policies referrer-policy
+      https script_name http_host remote_addr http_user_agent
+      http_authorization content_length raw_post_data
+    ].freeze
+    private_constant :VOWEL
+
+    attr_reader :info
+    attr_accessor :exporters, :summary_format, :default_action_descriptors,
+                  :unknown_action_descriptor, :default_subject, :fixture_path,
+                  :export_path, :default_response_content_type, :pretty_print,
+                  :ignored_header_values, :ignored_header_groups
+
+    def initialize
+      @info = Fictium::Configuration::Info.new
+      @exporters = [Fictium::OpenApi::V3Exporter.new]
+
+      @summary_format = method(:default_summary_format)
+      @pretty_print = true
+      setup_descriptors
+      setup_strings
+      @ignored_header_values = DEFAULT_IGNORED_HEADERS.dup
+      @ignored_header_groups = DEFAULT_IGNORED_HEADERS_GROUPS.dup
+    end
+
+    private
+
+    def setup_descriptors
+      @default_action_descriptors = {
+        default_summary_for_index: method(:default_summary_for_index),
+        default_summary_for_show: method(:default_summary_for_show),
+        default_summary_for_update: method(:default_summary_for_update),
+        default_summary_for_destroy: method(:default_summary_for_destroy)
+      }
+      @unknown_action_descriptor = method(:default_unknown_action_descriptor)
+    end
+
+    def setup_strings
+      @default_subject = 'This endpoint'
+      @export_path = 'doc'
+      @default_response_content_type = 'text/plain'
+    end
+
+    def default_summary_format(resources)
+      "Handles API #{resources}."
+    end
+
+    def default_unknown_action_descriptor(action, action_name)
+      name = action_name.humanize
+      "#{conjugate(name)} an existing #{action.resource.name}."
+    end
+
+    def default_summary_for_index(action)
+      "#{default_subject} lists all available #{action.resource.name.pluralize}"
+    end
+
+    def default_summary_for_show(action)
+      name = action.resource.name
+      "#{default_subject} shows details of #{get_preposition(name)} #{name}."
+    end
+
+    def default_summary_for_update(action)
+      name = action.resource.name
+      "#{default_subject} updates #{get_preposition(name)} #{name}."
+    end
+
+    def default_summary_for_destroy(action)
+      name = action.resource.name
+      "#{default_subject} destroys #{get_preposition(name)} #{name}."
+    end
+
+    def conjugate(name)
+      ::Verbs::Conjugator.conjugate name, subject: default_subject, tense: :present, person: :third
+    end
+
+    def get_preposition(resource_name)
+      resource_name.start_with?(VOWEL) ? 'an' : 'a'
+    end
+  end
+end

data/lib/fictium/configurations/info.rb

@@ -0,0 +1,12 @@
+module Fictium
+  class Configuration
+    class Info
+      attr_accessor :title, :description, :terms_of_service, :contract, :license, :version
+
+      def initialize
+        self.title = 'TODO: Change me at Fictium.configuration.api'
+        self.version = '0.1.0'
+      end
+    end
+  end
+end

data/lib/fictium/engine.rb

@@ -0,0 +1,6 @@
+module Fictium
+  class Engine < Rails::Engine
+    engine_name 'fictium'
+    isolate_namespace Fictium
+  end
+end

data/lib/fictium/evaluators/parameter_evaluator.rb

@@ -0,0 +1,57 @@
+module Fictium
+  class ParameterEvaluator
+    attr_reader :params
+
+    def initialize
+      @params = ActiveSupport::HashWithIndifferentAccess.new
+    end
+
+    def evaluate_params(&block)
+      if block.arity == 1
+        block.call(self)
+      else
+        instance_eval(&block)
+      end
+      @params
+    end
+
+    def method_missing(name, *_, **kwargs) # rubocop:disable Style/MethodMissingSuper
+      self[name] = validate_keys(**kwargs) if respond_to_missing?(name)
+    end
+
+    def [](name)
+      @params[name]
+    end
+
+    def []=(name, value)
+      @params[name] = value
+    end
+
+    private
+
+    def respond_to_missing?(_method_name, _include_private = false)
+      true
+    end
+
+    def validate_keys(required: false, deprecated: false, allow_empty: false, **kwargs)
+      {
+        description: kwargs[:description],
+        required: required,
+        deprecated: deprecated,
+        allow_empty: allow_empty,
+        schema: format_schema(kwargs)
+      }
+    end
+
+    def format_schema(args)
+      return unless args[:schema].present?
+
+      schema_evaluator.format(ref: args[:schema][:ref]) if args[:schema][:ref].present?
+      schema_evaluator.format(args[:schema])
+    end
+
+    def schema_evaluator
+      @schema_evaluator ||= Fictium::SchemaEvaluator.new
+    end
+  end
+end

data/lib/fictium/evaluators/schema_evaluator.rb

@@ -0,0 +1,7 @@
+module Fictium
+  class SchemaEvaluator
+    def format(obj)
+      obj[:ref].present? ? { '$ref': obj[:ref] } : obj
+    end
+  end
+end