gemfather 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 967f226be9ef886c0ab170cb4f440e85904c0a3e944b4a00ee4f65f662e0093f
+  data.tar.gz: b9e57b0f69e64fd5a04b257170a65ea7c546a39306d20f7e2c2e39a9c4e66cfa
+SHA512:
+  metadata.gz: d53bd3ec959d96ec41b2b10ee74c0ea8be9fa40186a73e3f9f4fef56470a0532da098ed3fc456b0b45a8c844c33d4646e11ac105a57fd2a105b198d55849f9e3
+  data.tar.gz: c5aea75f426d9da206194cd1ead6e4c41323fb766eb5266c97de5109a7422a199b31b9bc78201be2fa6f20d083ba6ea78595a3f490a82a2ff04250cb178de2ef

data/README.md

@@ -0,0 +1,145 @@
+# Gemfather
+
+![Gemfather image](/docs/gemfather.png?raw=true)
+
+### Гем для генерации API-гемов
+
+Установка
+
+`gem install gemfather`
+
+После установки гем добавляет в путь `$PATH` исполняемый скрипт `gemfather`, который позволит запускать `gemfather` из командной строки   
+
+`gemfather GEM_NAME` создает в текущем каталоге папку GEM_NAME c базовой структурой для гема API
+
+Описание нового проекта и документация по его конфигурированию и работе также будет сгененрирована в файле `GEM_NAME/README.md`
+
+Пример:
+```
+./gemfather domclick_new_api
+
+      create  domclick_new_api
+      create  domclick_new_api/domclick_new_api.gemspec
+      create  domclick_new_api/Dockerfile.test
+      create  domclick_new_api/Gemfile
+      create  domclick_new_api/Makefile
+      create  domclick_new_api/README.md
+      create  domclick_new_api/Rakefile
+      create  domclick_new_api/bin/console
+      create  domclick_new_api/bin/dc
+      create  domclick_new_api/bin/generate
+      create  domclick_new_api/lib/domclick_new_api.rb
+      create  domclick_new_api/lib/domclick_new_api/client.rb
+      create  domclick_new_api/lib/domclick_new_api/railtie.rb
+      create  domclick_new_api/lib/domclick_new_api/version.rb
+      create  domclick_new_api/spec/spec_helper.rb
+      create  domclick_new_api/log
+       chmod  domclick_new_api/bin/dc
+       chmod  domclick_new_api/bin/generate
+       chmod  domclick_new_api/bin/console
+         run  bundle binstubs rspec-core from "./domclick_new_api"
+         run  bin/rspec from "./domclick_new_api"
+```
+
+Внутри каталога есть исполняемый скрипт generate, который генерирует в проекте скаффолд для ручки сервиса
+
+Генерация скаффолда (api, model, specs) происходит следующим образом:
+`bin/generate namespace:action:post` 
+
+Пример: `bin/generate deals:create:post`
+
+Будет добавлена следующая структура каталогов и файлов
+```
+      create  ./lib/domclick_api/api
+      create  ./lib/domclick_api/api/deals.rb
+      create  ./lib/domclick_api/model/deals/create
+      create  ./lib/domclick_api/model/deals/create/request.rb
+      create  ./lib/domclick_api/model/deals/create/response.rb
+      create  ./spec/api
+      create  ./spec/api/deals_spec.rb
+      create  ./spec/model/deals/create
+      create  ./spec/model/deals/create/request_spec.rb
+      create  ./spec/model/deals/create/response_spec.rb
+```
+Таким образом, будет создана ручка, вызывающая путь `/create`, модели `request` и `response`, а также тесты для этой ручки
+
+## Пагинация
+
+Опционально, если добавить параметр `--paginate` - то ручка будет поддерживать пагинацию. Для конфигурации пагинации используется DSL:
+
+```ruby
+paginate :find_offers,
+         with: :limit_offset,
+         on_request: lambda { |req, limit: nil, offset: nil, sort: nil|
+           req.params[:limit] = limit if limit.present?
+           req.params[:offset] = offset if offset.present?
+           req.params[:sort] = sort if sort.present?
+         },
+         data_key: :offers,
+         limit: :limit.to_proc,
+         offset: :offset.to_proc,
+         total: :total.to_proc
+```
+
+```ruby
+paginate :find_offers,
+         with: :page,
+         on_request: lambda { |req, page: nil, per_page: nil, sort: nil|
+           req.params[:page] = page if page.present?
+           req.params[:per_page] = per_page if per_page.present?
+           req.params[:sort] = sort if sort.present?
+         },
+         data_key: :offers,
+         per_page: :per_page.to_proc,
+         total: :total.to_proc
+```
+
+Таким образом, метод `find_offers` будет возвращать объект relation, реализующий `Enumerable`.
+Данные при этом не будут загружены до тех пор, пока доступ к ним не понадобится (например, метод `#to_a`).
+
+## Опции DSL
+
+`with` - стратегия пагинации, стандартно поддерживаются `:page` и `:limit_offset`.
+`on_request` - коллбэк вызываемый при инициализации запроса. Позволяет нужным образом передать параметры (например, в теле или в хедерах).
+`data_key` - ключ, по которому можно получить массив данных из ответа.
+Может быть пустым, если данные лежат в корне, или массивом, если данные находятся в многоуровневой структуре (например, `[:data, :offers]`).
+`total` - коллбэк, по которому можно получить из ответа общее количество элементов на всех страницах (не обязательная опция).
+
+Опции, индивидуальные для стратегий пагинации:
+
+### Стратегия :page
+
+`per_page` - коллбэк, по которому можно получить из ответа количество элементов на одной странице (не обязательная опция).
+
+### Стратегия :limit_offset
+
+`limit` - коллбэк, по которому можно получить из ответа количество элементов на одной странице (не обязательная опция).
+`offset` - коллбэк, по которому можно получить из ответа текущее смещение (не обязательная опция).
+
+## Использование метода с пагинацией
+
+```ruby
+# Получение 100 записей, упорядоченных по id, начиная с 50-го элемента
+client.find_offers(company_id: 1).limit(100).offset(50).order(id: 'desc').to_a
+
+# Получение всех записей начиная с 50-го элемента
+client.find_offers(company_id: 1).limit(100).offset(50).all_remaining.to_a
+
+# Получение 10 записей на второй странице
+client.find_offers(company_id: 1).page(2).per_page(10).to_a
+
+# Получение всех записей начиная со второй страницы
+client.find_offers(company_id: 1).page(2).all_remaining.to_a
+
+# Получение первого элемента со второй страницы
+client.find_offers(company_id: 1).page(2).first
+
+# Получение полного ответа со второй страницы
+client.find_offers(company_id: 1).page(2).response
+
+# Получение общего количество элементов на всех страницах в сумме
+client.find_offers(company_id: 1).page(2).total
+
+# Получение общего количество элементов на всех страницах в сумме (сначала загрузит все страницы)
+client.find_offers(company_id: 1).page(2).total!
+```

data/bin/gemfather

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require_relative '../lib/api_generator'
+
+ApiGenerator::Services::Gemfather.new.generate_client(ARGV[0])
+

data/gem_template/%app_name%.gemspec.tt

@@ -0,0 +1,32 @@
+require_relative './lib/<%= app_short_name %>/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = '<%= app_name %>'
+  spec.version       = <%= app_name_class %>::Version::VERSION
+  spec.authors       = ['<%= author %>']
+  spec.email         = ['<%= email %>']
+
+  spec.summary       = 'API client for <%= app_name %> service'
+  spec.homepage      = 'https://TODO.INSERT/YOUR_REPO/HERE/'
+  spec.required_ruby_version = '>= 2.7'
+
+  spec.metadata = {
+    'bug_tracker_uri' => "#{spec.homepage}/issues",
+    'changelog_uri' => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    'documentation_uri' => "#{spec.homepage}/blob/main/README.md",
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => spec.homepage,
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir['lib/**/*', 'README.md']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'addressable', '~> 2.3'
+  spec.add_dependency 'dry-configurable', '~> 0.11'
+  spec.add_dependency 'gemfather', '~> <%= version %>'
+  spec.add_dependency 'faraday', '>= 0.17', '< 2'
+  spec.add_dependency 'faraday_middleware', '>= 0.13', '< 2'
+  spec.add_dependency 'hashie', '>= 3.0', '< 5'
+  spec.add_dependency 'zeitwerk', '>= 2.2.2'
+end

data/gem_template/.gitignore.tt

@@ -0,0 +1,26 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*
+!/log/.keep
+
+# Local environments file by gem 'dotenv'
+.env
+
+# Ingore all builded gems
+*.gem
+
+# Ignore local lock for gem developing
+Gemfile.lock
+
+coverage
+.rspec_status
+.rspec
+.yardoc

data/gem_template/.rubocop-rspec.yml.tt

@@ -0,0 +1,38 @@
+require: rubocop-rspec
+
+Metrics/BlockLength:
+  Exclude:
+    - app/admin/**/*.rb
+    - spec/**/*.rb
+
+Metrics/ModuleLength:
+  Exclude:
+    - spec/**/*.rb
+
+Style/SymbolProc:
+  Exclude:
+    - spec/factories/**/*.rb
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/HookArgument:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/FilePath:
+  Exclude:
+    - spec/requests/**/*.rb
+
+RSpec/DescribeClass:
+  Exclude:
+    - spec/lib/tasks/**/*.rb
+    - spec/config/*.rb
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false

data/gem_template/.rubocop-ruby.yml.tt

@@ -0,0 +1,54 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  Exclude:
+    - 'bin/**/*'
+  NewCops: enable
+
+Layout/LineLength:
+  Max: 100
+
+Bundler/OrderedGems:
+  Enabled: false
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/ClassStructure:
+  Enabled: true
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: true
+  Include:
+    - 'app/services/**/*'
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/Send:
+  Enabled: true
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+

data/gem_template/.rubocop.yml.tt

@@ -0,0 +1,11 @@
+require:
+  - rubocop-performance
+  - rubocop-rake
+
+inherit_from:
+  - .rubocop-ruby.yml
+  - .rubocop-rspec.yml
+
+inherit_mode:
+  merge:
+    - Exclude

data/gem_template/Gemfile.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source 'https://repo.sberned.ru/repository/rubygems-public/'
+
+# Specify your gem's dependencies in <%= app_name %>.gemspec
+gemspec
+
+gem 'bundler', '~> 2.0'
+gem 'rubocop', '~> 1.8'
+gem 'rubocop-performance'
+gem 'rubocop-rspec', '~> 2.1'
+gem 'rubocop-rake'
+gem 'dotenv', '~> 2.7'
+gem 'pry', '~> 0.13'
+gem 'rake', '~> 12.0'
+gem 'rspec', '~> 3.9'
+gem 'vcr', '~> 4.0'

data/gem_template/Makefile.tt

@@ -0,0 +1,21 @@
+default: lint test
+
+setup:
+	bundle install
+
+test:
+	bin/rspec
+
+lint:
+	bin/rubocop
+
+cleanup:
+	rm -f <%= app_name %>-*.gem
+
+build:
+	gem build <%= app_name %>.gemspec
+
+publish:
+	gem push <%= app_name %>-*.gem
+
+deploy: build publish cleanup

data/gem_template/README.md.tt

@@ -0,0 +1,180 @@
+# <%= app_name_class %>
+
+Ruby клиент для взаимодейтсвия с API сервиса [<%= app_name_class %> API](https://<%= app_name %>.dev/)
+
+## Установка
+
+Добавьте эту строку в Gemfile:
+
+```ruby
+gem '<%= app_name %>'
+```
+
+Выполните:
+
+```console
+    $ bundle
+```
+
+Или установите из командной строки:
+
+```console
+    $ gem install <%= app_name %>
+```
+
+## Конфигурация
+
+```ruby
+<%= app_name_class %>::Client.configure do |config|
+  config.api_endpoint       = 'https://<%= app_name %>.dev/'
+  config.api_user           = 'user'
+  config.api_password       = 'password'
+  config.open_timeout       = 5
+  config.read_timeout       = 5
+  config.user_agent         = 'info for debugging' # default is `Ruby <%= app_name_class %> API Client`
+  config.logger             = Logger.new(STDERR) # по дефолту `Rails.logger` в development окружении, в других - nil
+end
+```
+
+## Авторизация
+
+Из коробки есть:
+- По токену
+
+Для конфигурации в config нужно передать заголовок и сам токен
+```ruby
+config.api_token
+config.api_header
+```
+- Basic auth
+
+Для конфигурации в config нужно передать логин и пароль
+```ruby
+config.api_user
+config.api_password
+```
+- Для прочих кастомных настроек соединения при инициализации клиента передается блок
+
+```ruby
+<%= app_name_class %>::Client.new do |connection|
+    # кастомные настройки
+end
+```
+
+## Обработка ошибок
+Обработка ошибок реализована через DSL в клиенте вида
+
+`on_status 4XX, error: :error_name`
+
+При появлении статуса `4ХХ`, будет выброшено исключение `ErrorName`
+
+
+## Использование
+
+В папке `bin` существует скрипт `generate`, который генерирует в проекте скаффолд для ручки сервиса
+
+Генерация скаффолда (api, model, specs) происходит следующим образом:
+`bin/generate namespace:action:post`
+
+Пример: `bin/generate deals:create:post`
+
+Будет добавлена следующая структура каталогов и файлов
+```console
+      create  ./lib/domclick_api/api
+      create  ./lib/domclick_api/api/deals.rb
+      create  ./lib/domclick_api/model/deals/create
+      create  ./lib/domclick_api/model/deals/create/request.rb
+      create  ./lib/domclick_api/model/deals/create/response.rb
+      create  ./spec/api
+      create  ./spec/api/deals_spec.rb
+      create  ./spec/model/deals/create
+      create  ./spec/model/deals/create/request_spec.rb
+      create  ./spec/model/deals/create/response_spec.rb
+```
+Таким образом, будет создана ручка, вызывающая путь `/create`, модели `request` и `response`, а также тесты для этой ручки
+
+Вызов ручки:
+
+```ruby
+client = <%= app_name_class %>.client
+client.create(params)
+```
+Опционально, если добавить параметр `--paginate` - то ручка будет поддерживать пагинацию. Для конфигурации пагинации используется DSL:
+
+```ruby
+paginate :find_offers,
+         with: :limit_offset,
+         on_request: lambda { |req, limit: nil, offset: nil, sort: nil|
+           req.params[:limit] = limit if limit.present?
+           req.params[:offset] = offset if offset.present?
+           req.params[:sort] = sort if sort.present?
+         },
+         data_key: :offers,
+         limit: :limit.to_proc,
+         offset: :offset.to_proc,
+         total: :total.to_proc
+```
+
+```ruby
+paginate :find_offers,
+         with: :page,
+         on_request: lambda { |req, page: nil, per_page: nil, sort: nil|
+           req.params[:page] = page if page.present?
+           req.params[:per_page] = per_page if per_page.present?
+           req.params[:sort] = sort if sort.present?
+         },
+         data_key: :offers,
+         per_page: :per_page.to_proc,
+         total: :total.to_proc
+```
+
+Таким образом, метод `find_offers` будет возвращать объект relation, реализующий `Enumerable`.
+Данные при этом не будут загружены до тех пор, пока доступ к ним не понадобится (например, метод `#to_a`).
+
+```ruby
+client.find_offers(company_id: 1).limit(100).offset(50).order(id: 'desc').map(&:id)
+```
+
+## Разработка
+
+Установка:
+
+```console
+make setup
+```
+
+Тесты:
+
+```console
+make test
+```
+
+Рубокоп:
+
+```console
+make lint
+```
+
+Очистка:
+
+```console
+make cleanup
+```
+
+Создать docker образ:
+
+```console
+make build
+```
+
+Поставка гема в RubyGems:
+
+```console
+make publish
+```
+
+Деплой:
+
+```console
+make deploy
+```

data/gem_template/Rakefile.tt

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/gem_template/bin/console.tt

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'dotenv/load'
+require 'irb'
+require_relative '../lib/<%= app_name %>'
+
+<%= app_name_class %>::Client.configure do |configuration|
+  configuration.api_endpoint = 'http://server.dev'
+  configuration.api_token = 'TOKEN'
+
+  configuration.logger = Logger.new(STDOUT)
+end
+
+begin
+  # Put your test code here
+rescue StandardError => e
+  pp e
+end
+
+binding.irb

data/gem_template/bin/generate.tt

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'api_generator'
+require 'fileutils'
+
+ApiGenerator::Commands::Generate.new(ARGV[0..1]).call

data/gem_template/bin/rubocop.tt

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

data/gem_template/lib/%app_name%.rb.tt

@@ -0,0 +1,25 @@
+require 'addressable'
+require 'bundler/setup'
+require 'api_generator'
+require 'dry-configurable'
+require 'faraday'
+require 'faraday_middleware'
+require 'hashie'
+require 'time'
+require 'zeitwerk'
+
+require '<%= app_short_name %>/railtie' if defined?(Rails)
+
+module <%= app_short_name_class %>
+  def self.client
+    return @client if defined?(@client) && @client.class.same_config?(Client.config)
+
+    @client = Client.new(**Client.config.to_h)
+  end
+end
+
+loader = Zeitwerk::Loader.new
+loader.tag = File.basename(__FILE__, '.rb')
+loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+loader.push_dir("#{__dir__}/<%= app_short_name %>", namespace: <%= app_name_class %>)
+loader.setup

data/gem_template/lib/%app_short_name%/client.rb.tt

@@ -0,0 +1,18 @@
+module <%= app_short_name_class %>
+  class Client < ApiGenerator::Client::Connection
+    # INCLUDES
+
+    # ERROR_HANDLING
+    on_status 400, error: :invalid_request_error
+    on_status 401, error: :unauthorized_error
+    on_status 403, error: :forbidden_error
+    on_status 404, error: :resource_not_found_error
+    on_status 405, error: :method_not_allowed_error
+    on_status 413, error: :payload_too_large_error
+    on_status 422, error: :unprocessable_entity
+
+    def customize_connection!(connection)
+      # set custom authorization here if needed
+    end
+  end
+end

data/gem_template/lib/%app_short_name%/http_errors.rb.tt

@@ -0,0 +1,20 @@
+module <%= app_short_name_class %>
+  module HttpErrors
+    class ConnectionError < StandardError; end
+
+    class BaseError < StandardError
+      attr_reader :body
+
+      def initialize(msg = nil, body = nil)
+        @body = body if body
+        super(msg)
+      end
+    end
+
+    class ServerError < BaseError; end
+
+    class ClientError < BaseError; end
+
+    class UnsuccessfulRequestError < ClientError; end
+  end
+end