apiculture 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be857ef48fe8ec836d116ed89ed39c2cf55d2d60e4a25ae81eab0ccdf2b05f36
-  data.tar.gz: 737058ecf04cb0af193c24438f7c3a96c16a2551079aa13f4bcfbed2afa14fe8
+  metadata.gz: d78cc86595f72f0ec4ea08adaa5b545798eb54653aafedb47d3e6923351b3b76
+  data.tar.gz: 532aa3794d65dfd962d4d5984a29678e026b5da43efd1f5ad5dbaea4d4ee6ff1
 SHA512:
-  metadata.gz: 39564495733b83ca4ce0e1963b470d9836e5ce549827f93689bebfe4f5f8e57fb368497a407142f1c6c78143ad6c56a6a5a4f74ba29bdf199704bce58d720885
-  data.tar.gz: 6c1e15fe7e3c009349d17cf59d5686b81ccc6e6c94724a89b343b404afd3c013ee8505bebe75c3228774215f7065c1faf11872589de6e6b78abafe8d462f78f7
+  metadata.gz: b351b52e4a10c1c7ee2b7d4f7b5c8f63d4ed8b28f65348ebf63ec0f064ccb55b9bfd6cad6f21d49c34867436dfc50036e67f4d8fdb206f3525581346ee7db3a8
+  data.tar.gz: 9a0d97711023461335d4237f44e077daf2b1669c9509bb53dcd79571fb8a157188fb06b9d93db28ab9df69f170d152c50746ce8c27f73eb2af7781963d8e26bf

data/.gitignore

@@ -1,7 +1,3 @@
-# rcov generated
-coverage
-coverage.data
-
 # rdoc generated
 rdoc
 
@@ -16,7 +12,7 @@ Gemfile.lock
 # jeweler generated
 pkg
 
-# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
 #
 # * Create a file at ~/.gitignore
 # * Include files you want ignored
@@ -48,3 +44,5 @@ pkg
 
 # For rubinius:
 #*.rbc
+
+.ruby-version

data/.travis.yml

@@ -7,5 +7,7 @@ rvm:
   - 2.5
   - 2.6
   - 2.7
+  - 3.0
+  - 3.2
 sudo: false
 cache: bundler

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.2.0
+* Add ruby 3 support
+* Bump `mustermann` dependency to '~> 3'

data/apiculture.gemspec

@@ -4,14 +4,13 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'apiculture/version'
 
 Gem::Specification.new do |s|
-  s.name = "apiculture"
+  s.name = 'apiculture'
   s.version = Apiculture::VERSION
 
-  s.require_paths = ["lib"]
-  s.authors = ["Julik Tarkhanov", "WeTransfer"]
-  s.homepage       = 'http://github.com/wetransfer/zip_tricks'
-  s.description = "A toolkit for building REST APIs on top of Rack"
-  s.email = "me@julik.nl"
+  s.require_paths = ['lib']
+  s.authors = ['Julik Tarkhanov', 'WeTransfer']
+  s.description = 'A toolkit for building REST APIs on top of Rack'
+  s.email = 'me@julik.nl'
 
   # Prevent pushing this gem to RubyGems.org.
   # To allow pushes either set the 'allowed_push_host'
@@ -23,26 +22,26 @@ Gem::Specification.new do |s|
       'public gem pushes.'
   end
 
-  s.files = `git ls-files -z`.split("\x0")
+  s.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^spec/}) }
   s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.md"
+    'LICENSE.txt',
+    'README.md'
   ]
-  s.homepage = "https://github.com/WeTransfer/apiculture"
-  s.licenses = ["MIT"]
-  s.rubygems_version = "2.4.5.1"
-  s.summary = "Sweet API sauce on top of Rack"
+  s.homepage = 'https://github.com/WeTransfer/apiculture'
+  s.licenses = ['MIT']
+  s.rubygems_version = '2.4.5.1'
+  s.summary = 'Sweet API sauce on top of Rack'
 
-  s.add_runtime_dependency 'mustermann', '~> 1'
   s.add_runtime_dependency 'builder', '~> 3'
-  s.add_runtime_dependency 'rdiscount', '~> 2'
   s.add_runtime_dependency 'github-markup', '~> 3'
   s.add_runtime_dependency 'mustache', '~> 1'
+  s.add_runtime_dependency 'mustermann', '~> 3'
+  s.add_runtime_dependency 'rdiscount', '~> 2'
 
+  s.add_development_dependency 'bundler', '~> 2.0'
+  s.add_development_dependency 'cgi'
   s.add_development_dependency 'rack-test'
-  s.add_development_dependency "rspec", "~> 3"
-  s.add_development_dependency "rdoc", "~> 6.0"
-  s.add_development_dependency "rake"
-  s.add_development_dependency "bundler", "~> 1.0"
-  s.add_development_dependency "simplecov", ">= 0"
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rdoc', '~> 6.0'
+  s.add_development_dependency 'rspec', '~> 3'
 end

data/gemfiles/Gemfile.rack-1.x

@@ -9,9 +9,8 @@ gem 'mustache', '~> 1'
 
 group :development do
   gem 'rack-test'
-  gem "rspec", "~> 3.1", '< 3.2'
+  gem "rspec", "~> 3"
   gem "rdoc", "~> 6.0"
-  gem "rake", "~> 10"
-  gem "simplecov", ">= 0"
+  gem "rake"
   gem "bundler"
 end

data/gemfiles/Gemfile.rack-2.x

@@ -9,9 +9,8 @@ gem 'mustache', '~> 1'
 
 group :development do
   gem 'rack-test'
-  gem "rspec", "~> 3.1", '< 3.2'
+  gem "rspec", "~> 3"
   gem "rdoc", "~> 6.0"
-  gem "rake", "~> 10"
-  gem "simplecov", ">= 0"
+  gem "rake"
   gem "bundler"
 end

data/lib/apiculture/app.rb

@@ -13,19 +13,19 @@ class Apiculture::App
     end
 
     def get(url, **options, &handler_blk)
-      define_action :get, url, options, &handler_blk
+      define_action :get, url, **options, &handler_blk
     end
 
     def post(url, **options, &handler_blk)
-      define_action :post, url, options, &handler_blk
+      define_action :post, url, **options, &handler_blk
     end
 
     def put(url, **options, &handler_blk)
-      define_action :put, url, options, &handler_blk
+      define_action :put, url, **options, &handler_blk
     end
 
     def delete(url, **options, &handler_blk)
-      define_action :delete, url, options, &handler_blk
+      define_action :delete, url, **options, &handler_blk
     end
 
     def actions

data/lib/apiculture/app_documentation.rb

@@ -25,6 +25,10 @@ class Apiculture::AppDocumentation
   # Generates a Markdown string that contains the entire API documentation
   def to_markdown
     (['## %s' % @app_title] + to_markdown_slices).join("\n\n")
+  end 
+
+  def to_openapi
+    OpenApiDocumentation::Base.new(@app_title, @mountpoint, @chunks)
   end
   
   # Generates an HTML fragment string that can be included into another HTML document

data/lib/apiculture/openapi_documentation.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+require 'yaml'
+require 'base64'
+module OpenApiDocumentation
+  class Base
+    def initialize(app, prefix, chunks)
+      @app, @prefix = app, prefix
+      @paths = chunks.select { |chunk| chunk.respond_to?(:http_verb) }
+      @data = {
+        openapi: '3.0.0',
+        info: { 
+          title: @app.to_s, 
+          version: '0.0.1', 
+          description: @app.to_s + " " + chunks.select { |chunk| chunk.respond_to?(:to_markdown) }.map(&:to_markdown).join("\n")
+        },
+        tags: []
+      }
+      @data[:paths] = build_paths
+    end
+
+    def to_yaml
+      JSON.load(@data.to_json).to_yaml # trickery to get string based yaml
+    end
+
+    def paths
+      @data[:paths]
+    end
+
+    def spec
+      @data      
+    end
+
+    private
+
+    def build_paths
+      paths = {}
+      @paths.each do |path|
+        path = Path.new(path, @prefix, @app)
+        paths = merge_paths(paths, path)
+      end
+      paths
+    end
+
+    # We don't have deep_merge here so this is the poor man's alternative
+    def merge_paths(paths, path)
+      if paths.key?(path.name)
+        paths[path.name].merge!(path.build[path.name])
+      else
+        paths.merge!(path.build)
+      end
+      paths
+    end
+
+  end
+
+  class Path
+    VERBS_WITHOUT_BODY = %w(get head delete options)
+
+    def initialize(path, prefix, app)
+      @path, @prefix, @app = path, prefix, app
+    end
+
+    def build
+      request_body = build_request_body unless VERBS_WITHOUT_BODY.include?(@path.http_verb)
+      {
+        name =>
+        {
+          @path.http_verb.to_sym => {
+            summary: @path.description,
+            description: @path.description,
+            tags: [ @app.to_s ],
+            parameters: build_parameters,
+            requestBody: request_body,
+            responses: build_responses,
+            operationId: operation_id
+          }.delete_if { |_k, v| v.nil? || v.empty? }
+        }
+      }
+    end
+
+    def name
+      full_path = @path.path.to_s
+      @path.route_parameters.each do |parameter|
+        # This is a bit confusing but naming is a little different between
+        # apiculture and openapi
+        full_path.gsub!(":#{parameter.name}", "\{#{parameter.name}\}")
+      end
+      Util.clean_path("#{@prefix}#{full_path}")
+    end
+
+    private
+
+    def operation_id
+      # base64 encoding to make sure these ids are safe to use in an url
+      Base64.urlsafe_encode64("#{@path.http_verb}#{@prefix}#{@path.path}")
+    end
+
+    def build_parameters
+      if VERBS_WITHOUT_BODY.include?(@path.http_verb)
+        build_route_parameters + build_query_parameters
+      else
+        build_route_parameters
+      end
+    end
+
+    def build_route_parameters
+      route_params = @path.route_parameters.map do |parameter|
+        {
+          name: parameter.name,
+          description: parameter.description,
+          required: true,
+          in: :path,
+          schema: {
+            type: Util.map_type(parameter.matchable),
+            example: Util.map_example(parameter.matchable)
+          }
+        }
+      end
+      route_params
+    end
+
+    def build_query_parameters
+      params = @path.parameters.map do |parameter|
+        {
+          name: parameter.name,
+          description: parameter.description,
+          required: true,
+          in: :query,
+          schema: {
+            type: Util.map_type(parameter.matchable),
+            example: parameter.matchable
+          }
+        }
+      end
+      params
+    end
+
+    def build_request_body
+      return nil if VERBS_WITHOUT_BODY.include?(@path.http_verb)
+      
+      body_params = Hash[ @path.parameters.collect do |parameter|
+        [parameter.name, {
+          type: Util.map_type(parameter.matchable),
+          description: parameter.description
+        }]
+      end ]
+
+      return nil if body_params.count == 0
+
+      schema = {
+        type: :object,
+        properties: body_params
+      }
+
+      schema[:required] = @path.parameters.select(&:required).map(&:name) if @path.parameters.select(&:required).map(&:name).count > 0
+      {
+        content: {
+          "application/json": {
+            schema: schema
+          }
+        }
+      }
+    end
+
+    def build_responses
+      responses = Hash[@path.responses.collect do |response|
+        _response = {
+          description: response.description
+        }
+
+        unless response.jsonable_object_example.nil? || response.jsonable_object_example.empty?
+          _response[:content] = {
+            'application/json': {
+                schema: 
+                  { type: 'object',
+                  properties: Util.response_to_schema(response.jsonable_object_example) }
+            }
+          }
+        end
+
+        [response.http_status_code.to_s, _response]
+      end ]
+      responses
+    end
+  end
+
+  class Util
+    TYPES = {
+      String => 'string',
+      Integer => 'integer',
+      TrueClass => 'boolean'
+    }.freeze
+
+    EXAMPLES = {
+      String => 'string',
+      Integer => 1234,
+      TrueClass => true
+    }.freeze
+
+    def self.response_to_schema(response)
+      schema = {}
+      return nil if response.nil? || response.empty? || response.class == String
+      response.each do |key, value|
+        schema[key] = {
+          type: 'string',
+          example: value.to_s
+        }
+      end
+      schema
+    end
+
+    def self.map_type(type)
+      TYPES.fetch(type, 'string')
+    end
+
+    def self.map_example(type)
+      EXAMPLES.fetch(type, 'string')
+    end
+
+    def self.clean_path(path)
+      path.gsub(/\/\?\*\?$/, '')
+    end
+  end
+end

data/lib/apiculture/sinatra_instance_methods.rb

@@ -4,7 +4,7 @@ require 'json'
 module Apiculture::SinatraInstanceMethods
   NEWLINE = "\n"
   DEFAULT = :__default__
-  
+
   # Convert the given structure to JSON, set the content-type and
   # return the JSON string
   def json_response(structure, status: DEFAULT)
@@ -12,7 +12,7 @@ module Apiculture::SinatraInstanceMethods
     status(status) unless status == DEFAULT
     JSON.pretty_generate(structure)
   end
-  
+
   # Bail out from an action by sending a halt() via Sinatra. Is most useful for
   # handling access denied, invalid resource and other types of situations
   # where you don't want the request to continue, but still would like to
@@ -20,10 +20,10 @@ module Apiculture::SinatraInstanceMethods
   # with it's own JSON means.
   def json_halt(with_error_message, status: 400, **attrs_for_json_response)
     # Pretty-print + newline to be terminal-friendly
-    err_str = JSON.pretty_generate({error: with_error_message}.merge(attrs_for_json_response)) + NEWLINE
+    err_str = JSON.pretty_generate({error: with_error_message}.merge(**attrs_for_json_response)) + NEWLINE
     halt status, {'Content-Type' => 'application/json'}, [err_str]
   end
-  
+
   # Handles the given action via the given class, passing it the instance variables
   # given in the keyword arguments
   def action_result(action_class, **action_ivars)
@@ -31,7 +31,7 @@ module Apiculture::SinatraInstanceMethods
     unless call_result.is_a?(Array) || call_result.is_a?(Hash) || (call_result.nil? && @status == 204)
       raise "Action result should be an Array, a Hash or it can be nil but only if status is 204, instead it was a #{call_result.class}"
     end
-  
+
     json_response call_result if call_result
   end
 end

data/lib/apiculture/version.rb

@@ -1,3 +1,3 @@
 module Apiculture
-  VERSION = '0.1.6'
+  VERSION = '0.2.0'.freeze
 end