fictium 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5023f7f89561a94d98509eef482cac700d07c72e298ebbb206c99d8c6511a3b4
-  data.tar.gz: 2056592729db8666e2681b4ea0a113a27d780cf8e57d497b60363c5b18dacc93
+  metadata.gz: 421d8ab0b9aa1bb7982edf6cf39a156179f2ec1f02c72b7b79bb96e8cfc33f05
+  data.tar.gz: 936e8e3849fe1ef47f5c4af212cb7b3985def25284c1f755188f0b42a545b4e7
 SHA512:
-  metadata.gz: 9dc29def264f1cd01f92cebdd443bb8cec8cbccd284795b466ed290b7d847e2bb56b05d6bd83f802f25bd4e39f50d16fb31d013a436773f8ad646ab45d779230
-  data.tar.gz: a1dbe9bb9ad3439640669d29c18f43e423fdd96e1f4030e7a7da9921567856aaa1c989c419993a99b0805fc04778ea4a53de7903352f0625a2ab6072c78a2273
+  metadata.gz: 0cc22b7038a90471b18054314feaa182d558fcf29c6f79926ec9c1ccdce4267b69e1fda8b416b1605abbf3b0395c7210c1a17e11c29939fb86ef68e7a491f371
+  data.tar.gz: 29044b70d6d0ad7ad05f08eaa565979d43f0827dc554ab81c3c87926bede9b3ecd4b06c171e0071970c76017a5d0b7bfc0b43ca31a10b9b231b3d289614df54a

data/.gitignore

@@ -20,3 +20,5 @@ coverage
 .byebug_history
 
 coverage
+
+fictium-*.gem

data/CHANGELOG.md

@@ -17,6 +17,15 @@
 
 ## LOG
 
+### 0.2.0 (2019-11-12)
+
+New exporter: API Blueprint.
+
+#### Changes
+
+- Fixed some autocomplete from RSpec.
+- Created the new API Blueprint exporter.
+
 ### 0.1.0 (2019-11-06)
 
 Initial release, with Swagger exporter and RSpec integration.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    fictium (0.1.0)
+    fictium (0.2.0)
       activesupport (>= 5.3, < 6.2)
       json-schema (~> 2.8)
       verbs (~> 2.1.4)
@@ -71,7 +71,7 @@ GEM
     builder (3.2.3)
     byebug (11.0.1)
     concurrent-ruby (1.1.5)
-    crass (1.0.4)
+    crass (1.0.5)
     diff-lcs (1.3)
     docile (1.3.2)
     erubi (1.9.0)
@@ -85,7 +85,7 @@ GEM
     json (2.2.0)
     json-schema (2.8.1)
       addressable (>= 2.4)
-    loofah (2.2.3)
+    loofah (2.3.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
@@ -98,7 +98,7 @@ GEM
     mini_portile2 (2.4.0)
     minitest (5.12.0)
     nio4r (2.5.2)
-    nokogiri (1.10.4)
+    nokogiri (1.10.5)
       mini_portile2 (~> 2.4.0)
     parallel (1.18.0)
     parser (2.6.5.0)

data/README.md

@@ -7,7 +7,17 @@ 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.
+The current Gem version allows to export into the following formats:
+
+| Exporter    | Class name | Notes |
+|---          |---         |---    |
+| [OpenApi 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) | `Fictium::OpenApi::V3Exporter`    | The default exporter for the current Gem version. It doesn't include 100% of the OpenAPI specification, but it works for the most common use cases. It's the format [Swagger](https://swagger.io/) uses for documentation. |
+| [API Blueprint](https://apiblueprint.org/documentation/specification.html) | `Fictium::ApiBlueprintExporter`| Used by [Apiary](https://apiary.io/). A superset of Markdown with special keywords and controls. |
+
+Future versions may provide:
+
+  - OpenApi 1.0 and 2.0
+  - Custom HTML exporter
 
 ## Installation
 

data/lib/fictium/configurations/api_blueprint.rb

@@ -0,0 +1,31 @@
+module Fictium
+  class Configuration
+    class ApiBlueprint
+      attr_accessor :resources_group_name, :host, :footer_header,
+                    :api_version_formatter, :terms_of_service_formatter, :license_formatter
+
+      def initialize
+        self.host = 'https://change.me.at.api_blueprint.config'
+        self.resources_group_name = 'Resources'
+        self.footer_header = 'Information and references'
+        self.api_version_formatter = method(:format_api_version)
+        self.terms_of_service_formatter = method(:format_terms_of_service)
+        self.license_formatter = method(:format_license)
+      end
+
+      private
+
+      def format_api_version(api_version)
+        "API version: #{api_version}"
+      end
+
+      def format_terms_of_service(terms_of_service)
+        "[Terms of service](#{terms_of_service})."
+      end
+
+      def format_license(license)
+        "[#{license[:name]}](#{license[:url]}) license."
+      end
+    end
+  end
+end

data/lib/fictium/configurations/configuration.rb

@@ -8,18 +8,19 @@ module Fictium
       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
+      http_authorization content_length raw_post_data referrer-policy
     ].freeze
     private_constant :VOWEL
 
-    attr_reader :info
+    attr_reader :info, :api_blueprint
     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
+                  :ignored_header_values, :ignored_header_groups, :default_person
 
     def initialize
       @info = Fictium::Configuration::Info.new
+      @api_blueprint = Fictium::Configuration::ApiBlueprint.new
       @exporters = [Fictium::OpenApi::V3Exporter.new]
 
       @summary_format = method(:default_summary_format)
@@ -36,6 +37,7 @@ module Fictium
       @default_action_descriptors = {
         default_summary_for_index: method(:default_summary_for_index),
         default_summary_for_show: method(:default_summary_for_show),
+        default_summary_for_create: method(:default_summary_for_create),
         default_summary_for_update: method(:default_summary_for_update),
         default_summary_for_destroy: method(:default_summary_for_destroy)
       }
@@ -43,9 +45,10 @@ module Fictium
     end
 
     def setup_strings
-      @default_subject = 'This endpoint'
+      @default_subject = nil
       @export_path = 'doc'
       @default_response_content_type = 'text/plain'
+      @default_person = :second
     end
 
     def default_summary_format(resources)
@@ -54,30 +57,37 @@ module Fictium
 
     def default_unknown_action_descriptor(action, action_name)
       name = action_name.humanize
-      "#{conjugate(name)} an existing #{action.resource.name}."
+      "#{conjugate(name)} #{get_preposition(name)} #{action.resource.name}."
     end
 
     def default_summary_for_index(action)
-      "#{default_subject} lists all available #{action.resource.name.pluralize}"
+      "List 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}."
+      "Show details of #{get_preposition(name)} #{name}."
+    end
+
+    def default_summary_for_create(action)
+      name = action.resource.name
+      "Create a new #{name}."
     end
 
     def default_summary_for_update(action)
       name = action.resource.name
-      "#{default_subject} updates #{get_preposition(name)} #{name}."
+      "Update #{get_preposition(name)} #{name}."
     end
 
     def default_summary_for_destroy(action)
       name = action.resource.name
-      "#{default_subject} destroys #{get_preposition(name)} #{name}."
+      "Destroy #{get_preposition(name)} #{name}."
     end
 
     def conjugate(name)
-      ::Verbs::Conjugator.conjugate name, subject: default_subject, tense: :present, person: :third
+      ::Verbs::Conjugator.conjugate name, subject: default_subject,
+                                          tense: :present,
+                                          person: default_person
     end
 
     def get_preposition(resource_name)

data/lib/fictium/exporters/api_blueprint_exporter.rb

@@ -0,0 +1,65 @@
+require_relative 'api_blueprint_exporter/base_formatter'
+
+require_relative 'api_blueprint_exporter/header_formatter'
+require_relative 'api_blueprint_exporter/resource_formatter'
+require_relative 'api_blueprint_exporter/action_formatter'
+require_relative 'api_blueprint_exporter/example_formatter'
+require_relative 'api_blueprint_exporter/footer_formatter'
+
+module Fictium
+  class ApiBlueprintExporter
+    def export(document)
+      result = process_file(document).presence || ''
+      FileUtils.mkdir_p(File.dirname(export_file))
+      File.write(export_file, result)
+    end
+
+    private
+
+    def process_file(document)
+      list = [build_header(document), build_footer(document), build_resources(document)]
+      clean_items(list)
+    end
+
+    def export_file
+      @export_file ||=
+        File.join(Fictium.configuration.export_path, 'api_blueprint', 'api.apib')
+    end
+
+    def build_header(document)
+      header_formatter.format(document)
+    end
+
+    def build_resources(document)
+      mapped_resources = document.resources.map do |resource|
+        resource_formatter.format(resource)
+      end
+      mapped_resources = clean_items(mapped_resources)
+      mapped_resources.present? ? "# Group #{resources_group_name} \n\n#{mapped_resources}" : ''
+    end
+
+    def build_footer(document)
+      footer_formatter.format(document)
+    end
+
+    def header_formatter
+      HeaderFormatter.new
+    end
+
+    def resource_formatter
+      @resource_formatter ||= ResourceFormatter.new
+    end
+
+    def footer_formatter
+      FooterFormatter.new
+    end
+
+    def resources_group_name
+      Fictium.configuration.api_blueprint.resources_group_name
+    end
+
+    def clean_items(items)
+      items.select(&:present?).join("\n\n")
+    end
+  end
+end

data/lib/fictium/exporters/api_blueprint_exporter/action_formatter.rb

@@ -0,0 +1,32 @@
+module Fictium
+  class ApiBlueprintExporter
+    class ActionFormatter < Fictium::ApiBlueprintExporter::BaseFormatter
+      protected
+
+      def format_sections(action)
+        [build_header(action), build_examples(action)]
+      end
+
+      private
+
+      def build_header(action)
+        result = "## #{action.summary} [#{action.method.to_s.upcase} #{action.path}]"
+        description = action.description.present? ? "\n\n#{action.description}\n" : ''
+        "#{result}#{description}"
+      end
+
+      def build_examples(action)
+        default_example = action.default_example
+        examples = action.examples.reject { |example| example == default_example }
+        sections = ([default_example] + examples).map do |example|
+          example_formatter.format(example)
+        end
+        join_sections(sections)
+      end
+
+      def example_formatter
+        @example_formatter ||= ExampleFormatter.new
+      end
+    end
+  end
+end

data/lib/fictium/exporters/api_blueprint_exporter/base_formatter.rb

@@ -0,0 +1,16 @@
+module Fictium
+  class ApiBlueprintExporter
+    class BaseFormatter
+      def format(subject)
+        sections = format_sections(subject)
+        join_sections(sections)
+      end
+
+      protected
+
+      def join_sections(sections)
+        sections.each(&:strip).select(&:present?).join("\n\n")
+      end
+    end
+  end
+end

data/lib/fictium/exporters/api_blueprint_exporter/example_formatter.rb

@@ -0,0 +1,67 @@
+module Fictium
+  class ApiBlueprintExporter
+    class ExampleFormatter < Fictium::ApiBlueprintExporter::BaseFormatter
+      protected
+
+      def format_sections(example)
+        [format_request(example), format_response(example)]
+      end
+
+      private
+
+      def format_request(example)
+        return '' if example.request[:body].blank?
+
+        result = request_head(example)
+        result += "\n  #{example.description}\n" if example.description.present?
+        result += parse_http_object(example.request)
+        result
+      end
+
+      def format_response(example)
+        result = response_head(example)
+        result += parse_http_object(example.response)
+        result
+      end
+
+      def parse_http_object(http_object)
+        "#{parse_header(http_object[:header])}#{parse_body(http_object)}"
+      end
+
+      def parse_header(header)
+        return '' if header.blank?
+
+        mapped_headers = header.map do |key, value|
+          "            #{key}: #{value}"
+        end
+        <<~HEREDOC
+          \x20
+            + Header
+
+          #{mapped_headers.join("\n")}
+        HEREDOC
+      end
+
+      def request_head(example)
+        "+ Request #{example.summary} \n"
+      end
+
+      def response_head(example)
+        "+ Response #{example.response[:status]} (#{example.response[:content_type]})\n"
+      end
+
+      def parse_body(http_element)
+        return "\n  + Body" if http_element[:body].blank?
+
+        <<~HEREDOC
+          \x20
+            + Body
+
+                ```
+                #{http_element[:body]}
+                ```
+        HEREDOC
+      end
+    end
+  end
+end

data/lib/fictium/exporters/api_blueprint_exporter/footer_formatter.rb

@@ -0,0 +1,43 @@
+module Fictium
+  class ApiBlueprintExporter
+    class FooterFormatter < Fictium::ApiBlueprintExporter::BaseFormatter
+      delegate :configuration, to: :Fictium
+      delegate :info, :api_blueprint, to: :configuration
+      delegate :api_version_formatter, :terms_of_service_formatter, :license_formatter,
+               to: :api_blueprint
+
+      def format(document)
+        list = super(document)
+        list.present? ? "# #{api_blueprint.footer_header}\n\n#{list}" : ''
+      end
+
+      protected
+
+      def format_sections(_document)
+        [
+          api_version_reference,
+          terms_of_service_reference,
+          license_reference
+        ]
+      end
+
+      private
+
+      def api_version_reference
+        return '' if info.version.blank?
+
+        api_version_formatter.call(info.version)
+      end
+
+      def terms_of_service_reference
+        return '' if info.terms_of_service.blank?
+
+        terms_of_service_formatter.call(info.terms_of_service)
+      end
+
+      def license_reference
+        info.license.present? ? license_formatter.call(info.license) : ''
+      end
+    end
+  end
+end

data/lib/fictium/exporters/api_blueprint_exporter/header_formatter.rb

@@ -0,0 +1,28 @@
+module Fictium
+  class ApiBlueprintExporter
+    class HeaderFormatter
+      delegate :title, :description, to: :info
+
+      def format(_document)
+        <<~HEREDOC
+          Format: 1A
+          Host: #{host}
+
+          # #{title}
+
+          #{description}
+        HEREDOC
+      end
+
+      private
+
+      def info
+        Fictium.configuration.info
+      end
+
+      def host
+        Fictium.configuration.api_blueprint.host
+      end
+    end
+  end
+end

data/lib/fictium/exporters/api_blueprint_exporter/resource_formatter.rb

@@ -0,0 +1,31 @@
+module Fictium
+  class ApiBlueprintExporter
+    class ResourceFormatter < Fictium::ApiBlueprintExporter::BaseFormatter
+      protected
+
+      def format_sections(resource)
+        [build_header(resource), build_actions(resource)]
+      end
+
+      private
+
+      def build_header(resource)
+        header = "# #{resource.name&.pluralize&.humanize} [#{resource.base_path}]"
+        header += "\n#{resource.summary.capitalize}\n" if resource.summary.present?
+        description = resource.description.present? ? "\n#{resource.description}\n" : ''
+        "#{header}#{description}"
+      end
+
+      def build_actions(resource)
+        sections = resource.actions.map do |action|
+          action_formatter.format(action)
+        end
+        join_sections(sections)
+      end
+
+      def action_formatter
+        @action_formatter ||= ActionFormatter.new
+      end
+    end
+  end
+end

data/lib/fictium/loader.rb

@@ -1,5 +1,6 @@
 require_relative 'configurations/configuration'
 require_relative 'configurations/info'
+require_relative 'configurations/api_blueprint'
 
 require_relative 'evaluators/parameter_evaluator'
 require_relative 'evaluators/schema_evaluator'
@@ -13,3 +14,6 @@ require_relative 'poros/resource'
 
 # Require default (OpenApi v3) exporter
 require_relative 'exporters/open_api/v3_exporter'
+
+# Other exporters created by this gem
+require_relative 'exporters/api_blueprint_exporter'

data/lib/fictium/rspec/actions.rb

@@ -20,6 +20,14 @@ module Fictium
           metadata[:fictium_action].add_params_in(section, &block)
         end
 
+        def action_summary(text)
+          metadata[:fictium_action].summary = text
+        end
+
+        def action_description(text)
+          metadata[:fictium_action].description = text
+        end
+
         def example(*args, **kwargs)
           Fictium::RSpec::Proxies::Example.new(self, args, kwargs)
         end

data/lib/fictium/rspec/autocomplete/example.rb

@@ -8,7 +8,8 @@ module Fictium
             example.response.merge!(
               status: response.status,
               body: response.body,
-              content_type: response.content_type
+              content_type: response.content_type,
+              header: filter_header(response.header.to_h)
             )
             process_http_request(example, response.request)
             return unless example.default?
@@ -26,7 +27,8 @@ module Fictium
             example.request ||= {}
             example.request.merge!(
               content_type: request.content_type,
-              body: request.body.string
+              body: request.body.string,
+              header: filter_header(request.headers.to_h)
             )
             extract_method(example, request)
             return unless example.default?
@@ -38,6 +40,30 @@ module Fictium
             action = example.action
             action.method = request.method.downcase.to_sym if action.method.blank?
           end
+
+          def filter_header(header)
+            valid_keys = header.keys.select { |name| valid_header?(name) }
+            header.slice(*valid_keys).transform_keys do |key|
+              (key.start_with?('HTTP_') ? key.sub('HTTP_', '') : key).sub('_', '-')
+            end
+          end
+
+          def valid_header?(name)
+            downcase_name = name.downcase
+            out_of_header_group?(downcase_name) && out_of_excluded_headers?(downcase_name)
+          end
+
+          def out_of_header_group?(name)
+            ignored_header_groups.none? { |group| name.start_with?(group) }
+          end
+
+          def out_of_excluded_headers?(name)
+            Fictium.configuration.ignored_header_values.exclude?(name)
+          end
+
+          def ignored_header_groups
+            Fictium.configuration.ignored_header_groups
+          end
         end
       end
     end

data/lib/fictium/version.rb

@@ -1,5 +1,5 @@
 module Fictium
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
   RAILS_MIN_VERSION = '>= 5.3'.freeze
   RAILS_MAX_VERSION = '< 6.2'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fictium
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ramiro Rojo
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-06 00:00:00.000000000 Z
+date: 2019-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -258,11 +258,19 @@ files:
 - bin/setup
 - fictium.gemspec
 - lib/fictium.rb
+- lib/fictium/configurations/api_blueprint.rb
 - lib/fictium/configurations/configuration.rb
 - lib/fictium/configurations/info.rb
 - lib/fictium/engine.rb
 - lib/fictium/evaluators/parameter_evaluator.rb
 - lib/fictium/evaluators/schema_evaluator.rb
+- lib/fictium/exporters/api_blueprint_exporter.rb
+- lib/fictium/exporters/api_blueprint_exporter/action_formatter.rb
+- lib/fictium/exporters/api_blueprint_exporter/base_formatter.rb
+- lib/fictium/exporters/api_blueprint_exporter/example_formatter.rb
+- lib/fictium/exporters/api_blueprint_exporter/footer_formatter.rb
+- lib/fictium/exporters/api_blueprint_exporter/header_formatter.rb
+- lib/fictium/exporters/api_blueprint_exporter/resource_formatter.rb
 - lib/fictium/exporters/open_api/schemas/3.0.0.json
 - lib/fictium/exporters/open_api/v3_exporter.rb
 - lib/fictium/exporters/open_api/v3_exporter/content_formatter.rb