ropen_pi 0.2.0

data/examples/docker-compose.yml

@@ -0,0 +1,86 @@
+version: '3.7'
+
+# shared variables to keep things DRY
+x-shared-env: &shared
+  DB_HOST: ${DB_HOST}
+  DB_USER: ${DB_USER}
+  DB_NAME: ${DB_NAME}
+  DB_PASSWORD: ${DB_PASSWORD}
+  SVC_NAME: ${SVC_NAME}
+  SVC_SHORT: ${SVC_SHORT}
+
+networks:
+  net__backend: ~
+
+  netext__traefik:
+    external: true
+
+volumes:
+  # saves the gems as a mount that's used by docker
+  bundle: ~
+
+services:
+  svc:
+    container_name: ${SVC_NAME}
+    depends_on:
+      - db
+    entrypoint: resources/docker/docker-entrypoint.sh
+    environment:
+      <<: *shared
+    image: talentplatforms/ruby:${RUBY_IMAGE_VERSION}
+    labels:
+      - org.label-schema.name=${SVC_NAME}
+      - org.label-schema.description=${SVC_DESCRIPTION}
+      - org.label-schema.version=1.0.0
+    networks:
+      - net__backend
+    stdin_open: true
+    # the tmp folder should not be kept, so it's an ephemeral mount
+    # this also speeds up requests
+    tmpfs:
+      - /app/log
+      - /app/tmp
+    tty: true
+    volumes:
+      - .:/app:cached
+      - bundle:/bundle
+
+  db:
+    container_name: ${DB_HOST}
+    environment:
+      POSTGRES_USER: ${DB_USER}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_DB: ${DB_NAME}
+    image: postgres:10-alpine
+    networks:
+      - net__backend
+    ports:
+      # the db port to be used by external guis. this also needs to be changed
+      - ${DB_EXPOSED_PORT}:5432
+
+  # this is just a development helper that displays the
+  # created openApi documentation
+  # https://github.com/swagger-api/swagger-ui/tree/master/docs
+  # swagger:
+  #   container_name: ${SVC_NAME}-swagger
+  #   environment:
+  #     URLS: "[{ url: \"${SWAGGER_ENDPOINT}\", name: \"${SVC_NAME}\" }]"
+  #   image: swaggerapi/swagger-ui:v3.23.9
+  #   labels:
+  #     # traefik stuff
+  #     - traefik.enable=true
+  #     - traefik.docker.network=netext__traefik
+  #     # http
+  #     - traefik.http.routers.${SVC_NAME}-swagger.rule=Host(`swagger.${SVC_NAME}.localhost`)
+  #     - traefik.http.routers.${SVC_NAME}-swagger.entrypoints=http
+  #     - traefik.http.routers.${SVC_NAME}-swagger.service=${SVC_NAME}-swagger
+  #     - traefik.http.routers.${SVC_NAME}-swagger.middlewares.redirect=redirect@file
+  #     # https
+  #     - traefik.http.routers.${SVC_NAME}-swagger-ssl.rule=Host(`swagger.${SVC_NAME}.localhost`)
+  #     - traefik.http.routers.${SVC_NAME}-swagger-ssl.entrypoints=https
+  #     - traefik.http.routers.${SVC_NAME}-swagger-ssl.tls=true
+  #     - traefik.http.services.${SVC_NAME}-swagger.loadbalancer.server.port=8080
+  #   networks:
+  #     - netext__traefik
+  #   volumes:
+  #     - ./resources/open-api:/swagger

data/examples/resources/docker/docker-entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+set -ex
+
+# Check or install the app dependencies via Bundler:
+bundle check || bundle
+
+# Specify a default command, in case it wasn't issued:
+if [ -z "$1" ]; then
+  set -- bundle exec rails s -b 0.0.0.0 -p 3000 "$@"
+fi
+
+# Execute the given or default command:
+exec "$@"
+

data/lib/generators/ropen_pi/USAGE

@@ -0,0 +1,8 @@
+Description:
+  Adds open_api_helper to enable Swagger DSL in integration specs
+
+Example:
+    rails generate rswag:specs:install
+
+    This will create:
+        spec/open_api_helper.rb

data/lib/generators/ropen_pi/install_generator.rb

@@ -0,0 +1,12 @@
+require 'rails/generators'
+module Generators
+  module RopenPi
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def add_open_api_helper
+        template('ropen_pi_helper.rb', 'spec/ropen_pi_helper.rb')
+      end
+    end
+  end
+end

data/lib/generators/ropen_pi/templates/ropen_pi_helper.rb

@@ -0,0 +1,25 @@
+require 'rails_helper'
+
+RSpec.configure do |config|
+  config.root_dir = Rails.root.join('open-api').to_s
+  config.open_api_docs = {
+    'v1/openapi.json' => {
+      openapi: '3.0.0',
+      info: {
+        title: 'API V1',
+        version: 'v1'
+      },
+      paths: {},
+      servers: [
+        {
+          url: 'https://{defaultHost}',
+          variables: {
+            defaultHost: {
+              default: 'www.example.com'
+            }
+          }
+        }
+      ]
+    }
+  }
+end

data/lib/ropen_pi.rb

@@ -0,0 +1,5 @@
+require 'ropen_pi/specs'
+require 'ropen_pi/version'
+
+module RopenPi
+end

data/lib/ropen_pi/config_helper.rb

@@ -0,0 +1,144 @@
+# helper for the open api documentation
+module RopenPi
+  module Param
+    #
+    def self.date_param(name, desc: 'tba', opts: {})
+      param(name, :string, fmt: 'date-time', desc: desc, opts: opts)
+    end
+
+    def self.uuid_param(name, desc: 'tba', opts: {})
+      param(name, :string, fmt: 'uuid', desc: desc, opts: opts)
+    end
+
+    def self.string_param(name, desc: 'tba', opts: {})
+      param(name, :string, desc: desc, opts: opts)
+    end
+
+    def self.int_param(name, desc: 'tba', opts: {})
+      param(name, :integer, desc: desc, opts: opts)
+    end
+
+    def self.bool_param(name, desc: 'tba', opts: {})
+      param(name, :boolean, desc: desc, opts: opts)
+    end
+
+    def self.ref_param(name, ref, desc: 'tba', opts: {})
+      param(name, 'null', desc: desc, opts: opts).merge(schema: { '$ref': ref })
+    end
+
+    def self.param_in_path(name, schema_type, fmt: nil, desc: 'tba', opts: {})
+      param(name, schema_type, fmt: fmt, desc: desc, opts: opts)
+        .merge(
+          in: 'path',
+          required: true
+        )
+        .merge(opts)
+    end
+
+    def self.param(name, schema_type, fmt: nil, desc: 'tba', opts: {})
+      {
+        name: name.to_s,
+        description: desc,
+        in: 'query',
+        schema: schema(schema_type, fmt: fmt)
+      }.merge(opts)
+    end
+
+    def self.schema(type, fmt: nil)
+      {}.tap do |schema|
+        schema[:type] = type.to_s
+        schema[:format] = fmt.to_s if fmt.present?
+      end
+    end
+
+    def self.schema_enum(values, type: :string)
+      {
+        type: type.to_s,
+        enum: values
+      }
+    end
+
+    class << self  
+      alias boolean_param bool_param
+      alias integer_param int_param
+    end
+  end
+
+  module Type
+    def self.date_time_type(opts = { example: '2020-02-02' })
+      string_type(opts).merge(format: 'date-time')
+    end
+
+    def self.email_type(opts = { example: 'han.solo@example.com' })
+      string_type(opts).merge(format: 'email')
+    end
+
+    def self.uuid_type(opts = { example: 'abcd12-1234ab-abcdef123' })
+      string_type(opts).merge(format: 'uuid')
+    end
+
+    def self.string_type(opts = { example: 'Example string' })
+      type('string', opts)
+    end
+
+    def self.integer_type(opts = { example: 1 })
+      type('integer', opts)
+    end
+
+    def self.bool_type(opts = { example: true })
+      type('boolean', opts)
+    end
+
+    def self.type(thing, opts = {})
+      { type: thing }.merge(opts)
+    end
+
+    def self.string_array_type(opts = {})
+      {
+        type: 'array',
+        items: { type: 'string', example: 'Example string' }
+       }.merge(opts)
+    end
+
+    def self.ref_type(ref)
+      { '$ref': ref }
+    end
+
+    class << self  
+      alias boolean_type bool_type
+      alias int_type integer_type
+    end
+  end
+
+  module Response
+    # rubocop:disable Metrics/MethodLength
+    def self.collection(ref, desc: 'tba', type: RopenPi::APP_JSON)
+      {
+        description: desc,
+        content: {
+          type => {
+            schema: {
+              type: 'object',
+              properties: { data: { type: :array, items: { '$ref': ref } } }
+            }
+          }
+        }
+      }
+    end
+
+    def self.single(ref, desc: 'tba', type: RopenPi::APP_JSON)
+      {
+        description: desc,
+        content: {
+          type => {
+            schema: {
+              type: 'object',
+              properties: { data: { '$ref': ref } }
+            }
+          }
+        }
+      }
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end

data/lib/ropen_pi/specs.rb

@@ -0,0 +1,23 @@
+require 'rspec/core'
+require 'ropen_pi/specs/example_group_helpers'
+require 'ropen_pi/specs/example_helpers'
+require 'ropen_pi/specs/configuration'
+require 'ropen_pi/specs/railtie' if defined?(Rails::Railtie)
+
+module RopenPi
+  module Specs
+    # Extend RSpec with a swagger-based DSL
+    ::RSpec.configure do |config|
+      config.add_setting :root_dir
+      config.add_setting :open_api_docs
+      config.add_setting :open_api_output_format
+
+      config.extend ExampleGroupHelpers, type: :request
+      config.include ExampleHelpers, type: :request
+    end
+
+    def self.config
+      @config ||= Configuration.new(RSpec.configuration)
+    end
+  end
+end

data/lib/ropen_pi/specs/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+module RopenPi
+  module Specs
+    class Configuration
+      def initialize(rspec_config)
+        @rspec_config = rspec_config
+      end
+
+      def root_dir
+        @root_dir ||= begin
+          raise ConfigurationError, 'No root_dir provided. See open_api_helper.rb' if @rspec_config.root_dir.nil?
+
+          @rspec_config.root_dir
+        end
+      end
+
+      def open_api_output_format
+        @open_api_output_format ||= begin
+          @rspec_config.open_api_output_format || :json
+        end
+      end
+
+      def open_api_docs
+        @open_api_docs ||= begin
+          if @rspec_config.open_api_docs.nil? || @rspec_config.open_api_docs.empty?
+            raise ConfigurationError, 'No open_api_docs defined. See open_api_helper.rb'
+          end
+
+          @rspec_config.open_api_docs
+        end
+      end
+
+      def get_doc(name)
+        return open_api_docs.values.first if name.nil?
+
+        raise ConfigurationError, "Unknown doc '#{name}'" unless open_api_docs[name]
+
+        open_api_docs[name]
+      end
+    end
+    
+    class ConfigurationError < StandardError; end
+  end
+end
+

data/lib/ropen_pi/specs/example_group_helpers.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+# @TODO: replace hashie!
+require 'hashie'
+
+module RopenPi
+  module Specs
+    # rubocop:disable Metrics/ModuleLength
+    module ExampleGroupHelpers
+      def path(template, metadata = {}, &block)
+        metadata[:path_item] = { template: template }
+        describe(template, metadata, &block)
+      end
+
+      %i[get post patch put delete head].each do |verb|
+        define_method(verb) do |summary, &block|
+          api_metadata = { operation: { verb: verb, summary: summary } }
+          describe(verb, api_metadata, &block)
+        end
+      end
+
+      %i[operationId deprecated security].each do |attr_name|
+        define_method(attr_name) do |value|
+          metadata[:operation][attr_name] = value
+        end
+      end
+
+      # NOTE: 'description' requires special treatment because ExampleGroup already
+      # defines a method with that name. Provide an override that supports the existing
+      # functionality while also setting the appropriate metadata if applicable
+      def description(value = nil)
+        return super() if value.nil?
+
+        metadata[:operation][:description] = value
+      end
+
+      # These are array properties - note the splat operator
+      %i[tags consumes produces schemes].each do |attr_name|
+        define_method(attr_name) do |*value|
+          metadata[:operation][attr_name] = value
+        end
+      end
+
+      def request_body(attributes)
+        # can make this generic, and accept any incoming hash (like parameter method)
+        attributes.compact!
+
+        if metadata[:operation][:requestBody].blank?
+          metadata[:operation][:requestBody] = attributes
+        elsif metadata[:operation][:requestBody] && metadata[:operation][:requestBody][:content]
+          # merge in
+          content_hash = metadata[:operation][:requestBody][:content]
+          incoming_content_hash = attributes[:content]
+          content_hash.merge!(incoming_content_hash) if incoming_content_hash
+        end
+      end
+
+      def request_body_json(schema:, required: true, description: nil, examples: nil)
+        passed_examples = Array(examples)
+        content_hash = { 'application/json' => { schema: schema, examples: examples }.compact! || {} }
+        request_body(description: description, required: required, content: content_hash)
+
+        handle_examples(schema: schema, examples: passed_examples, required: required) if passed_examples.any?
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def handle_examples(schema:, examples:, required:)
+        # the request_factory is going to have to resolve the different ways that the example can be given
+        # it can contain a 'value' key which is a direct hash (easiest)
+        # it can contain a 'external_value' key which makes an external call to load the json
+        # it can contain a '$ref' key. Which points to #/components/examples/blog
+        # rubocop:disable Metrics/BlockLength
+        examples.each do |passed_example|
+          param_attributes =  if passed_example.is_a?(Symbol)
+                                example_key_name = passed_example
+                                # TODO: write more tests around this adding to the parameter
+                                # if symbol try and use save_request_example
+                                {
+                                  name: example_key_name,
+                                  in: :body,
+                                  required: required,
+                                  param_value: example_key_name,
+                                  schema: schema
+                                }
+                              elsif passed_example.is_a?(Hash) && passed_example[:externalValue]
+                                {
+                                  name: passed_example,
+                                  in: :body,
+                                  required: required,
+                                  param_value: passed_example[:externalValue],
+                                  schema: schema
+                                }
+                              elsif passed_example.is_a?(Hash) && passed_example['$ref']
+                                {
+                                  name: passed_example,
+                                  in: :body,
+                                  required: required,
+                                  param_value: passed_example['$ref'],
+                                  schema: schema
+                                }
+                              end
+          parameter(param_attributes)
+        end
+        # rubocop:enable Metrics/BlockLength
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def request_body_text_plain(required: false, description: nil, examples: nil)
+        content_hash = { 'test/plain' => { schema: {type: :string}, examples: examples }.compact! || {} }
+        request_body(description: description, required: required, content: content_hash)
+      end
+
+      # TODO: add examples to this like we can for json, might be large lift
+      # as many assumptions are made on content-type
+      def request_body_xml(schema:, required: false, description: nil, examples: nil)
+        passed_examples = Array(examples)
+        content_hash = { 'application/xml' => { schema: schema, examples: examples }.compact! || {} }
+        request_body(description: description, required: required, content: content_hash)
+      end
+
+      def request_body_multipart(schema:, description: nil)
+        content_hash = { 'multipart/form-data' => { schema: schema } }
+        request_body(description: description, content: content_hash)
+
+        schema.extend(Hashie::Extensions::DeepLocate)
+        file_properties = schema.deep_locate ->(_k, v, _obj) { v == :binary }
+        hash_locator = []
+
+        file_properties.each do |match|
+          hash_match = schema.deep_locate ->(_k, v, _obj) { v == match }
+          hash_locator.concat(hash_match) unless hash_match.empty?
+        end
+
+        property_hashes = hash_locator.flat_map do |locator|
+          locator.select { |_k, v| file_properties.include?(v) }
+        end
+
+        existing_keys = []
+        property_hashes.each do |property_hash|
+          property_hash.keys.each do |k|
+            next if existing_keys.include?(k)
+
+            file_name = k
+            existing_keys << k
+            parameter name: file_name, in: :formData, type: :file, required: true
+          end
+        end
+      end
+
+      def parameter(attributes)
+        attributes[:required] = true if attributes[:in] && attributes[:in].to_sym == :path
+        attributes[:schema] = { type: attributes[:type] } if attributes[:type] && attributes[:schema].nil?
+
+        if metadata.key?(:operation)
+          metadata[:operation][:parameters] ||= []
+          metadata[:operation][:parameters] << attributes
+        else
+          metadata[:path_item][:parameters] ||= []
+          metadata[:path_item][:parameters] << attributes
+        end
+      end
+
+      def response(code, description, metadata = {}, &block)
+        metadata[:response] = { code: code, description: description }
+        context(description, metadata, &block)
+      end
+
+      def schema(value, content_type: 'application/json')
+        content_hash = { content_type => { schema: value } }
+        metadata[:response][:content] = content_hash
+      end
+
+      def header(name, attributes)
+        metadata[:response][:headers] ||= {}
+
+        if attributes[:type] && attributes[:schema].nil?
+          attributes[:schema] = { type: attributes[:type] }
+          attributes.delete(:type)
+        end
+
+        metadata[:response][:headers][name] = attributes
+      end
+
+      # NOTE: Similar to 'description', 'examples' need to handle the case when
+      # being invoked with no params to avoid overriding 'examples' method of
+      # rspec-core ExampleGroup
+      def examples(example = nil)
+        return super() if example.nil?
+
+        metadata[:response][:examples] = example
+      end
+
+      # checks the examples in the parameters should be able to add $ref and externalValue examples.
+      # This syntax would look something like this in the integration _spec.rb file
+      #
+      # request_body_json schema: { '$ref' => '#/components/schemas/blog' },
+      #   examples: [:blog, {name: :external_blog,
+      #                       externalValue: 'http://api.sample.org/myjson_example'},
+      #                     {name: :another_example,
+      #                       '$ref' => '#/components/examples/flexible_blog_example'}]
+      # The first value :blog, points to a let param of the same name, and is used to make the request in the
+      # integration test (it is used to build the request payload)
+      #
+      # The second item in the array shows how to add an externalValue for the examples in the requestBody section
+      # The third item shows how to add a $ref item that points to the components/examples section of the swagger spec.
+      #
+      # NOTE: that the externalValue will produce valid example syntax in the swagger output, but swagger-ui
+      # will not show it yet
+      def merge_other_examples!(example_metadata)
+        # example.metadata[:operation][:requestBody][:content]['application/json'][:examples]
+        content_node = example_metadata[:operation][:requestBody][:content]['application/json']
+        return unless content_node
+
+        external_example = example_metadata[:operation]&.dig(:parameters)&.detect do |p|
+          p[:in] == :body && p[:name].is_a?(Hash) && p[:name][:externalValue]
+        end || {}
+
+        ref_example = example_metadata[:operation]&.dig(:parameters)&.detect do |p|
+          p[:in] == :body && p[:name].is_a?(Hash) && p[:name]['$ref']
+        end || {}
+
+        examples_node = content_node[:examples] ||= {}
+
+        nodes_to_add = []
+        nodes_to_add << external_example unless external_example.empty?
+        nodes_to_add << ref_example unless ref_example.empty?
+
+        nodes_to_add.each do |node|
+          json_request_examples = examples_node ||= {}
+          other_name = node[:name][:name]
+          other_key = node[:name][:externalValue] ? :externalValue : '$ref'
+
+          json_request_examples.merge!(other_name => { other_key => node[:param_value] }) if other_name
+        end
+      end
+
+      def run_test!(&block)
+        app_json = 'application/json'
+
+        before do |example|
+          submit_request(example.metadata)
+        end
+
+        it "returns a #{metadata[:response][:code]} response" do |example|
+          assert_response_matches_metadata(example.metadata, &block)
+          example.instance_exec(response, &block) if block_given?
+        end
+
+        after do |example|
+          body_parameter = example.metadata[:operation]&.dig(:parameters)&.detect do |p|
+            p[:in] == :body && p[:required]
+          end
+
+          if body_parameter && respond_to?(body_parameter[:name]) && \
+             example.metadata[:operation][:requestBody][:content][app_json]
+
+            # save response examples by default
+            if example.metadata[:response][:examples].nil? || example.metadata[:response][:examples].empty?
+              unless response.body.to_s.empty?
+                example.metadata[:response][:examples] = {
+                  app_json => JSON.parse(response.body, symbolize_names: true)
+                }
+              end
+            end
+
+            # save request examples using the let(:param_name) { REQUEST_BODY_HASH } syntax in the test
+            if response.code.to_s =~ /^2\d{2}$/
+
+              example.metadata[:operation][:requestBody][:content][app_json] = { examples: {} } \
+                unless example.metadata[:operation][:requestBody][:content][app_json][:examples]
+
+              json_request_examples = example.metadata[:operation][:requestBody][:content][app_json][:examples]
+              json_request_examples[body_parameter[:name]] = { value: send(body_parameter[:name]) }
+
+              example.metadata[:operation][:requestBody][:content][app_json][:examples] = json_request_examples
+            end
+          end
+
+          self.class.merge_other_examples!(example.metadata) if example.metadata[:operation][:requestBody]
+        end
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end