Merge pull request #56 from epimorphics/issue/55-initialize-with-endp…

…oints-directory

Allow initialization from endpointSpecs directory

CHANGELOG.md

@@ -2,13 +2,19 @@
 
 All notable changes will be documented in this file.
 
+## 1.2.0 - 2024-10-08
+
+- (AlexT) allow passing endpoint specifications directory in initializer
+  Bump deps including minitest 5.15.0 -> 5.25.1, mocha 1.13.0 -> 2.4.5 and
+  minitest-reporters 1.5.0 -> 1.7.1.
+
 ## 1.1.4 - 2024-10-08
 
 - (Dan) Upgrades ruby version to 2.7.8 and version cadence to 1.1.4
 
 ## 1.1.3 - 2024-06-03
 
-- (AlexT) require 'ostruct' to fix tests in Ruby 3.3.1. Use Matrix tests to check
+- (AlexT) require 'ostruct' to fix tests in Ruby 3.3.1. Use Matrix tests to check 
   multiple Ruby versions, 2.7 to 3.3. Bump deps:
   - rexml 3.2.5 -> 3.2.8 fixing CVE-2024-35176
   - concurrent-ruby 1.1.9 -> 1.3.1

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sapi-client-ruby (1.1.4)
+    sapi-client-ruby (1.2.0)
       faraday_middleware (~> 1.0.0)
       i18n (~> 1.5)
 
@@ -10,7 +10,7 @@ GEM
   specs:
     ansi (1.5.0)
     ast (2.4.2)
-    builder (3.2.4)
+    builder (3.3.0)
     byebug (11.1.3)
     concurrent-ruby (1.3.4)
     docile (1.4.0)
@@ -41,13 +41,14 @@ GEM
       faraday (~> 1.0)
     i18n (1.14.6)
       concurrent-ruby (~> 1.0)
-    minitest (5.15.0)
-    minitest-reporters (1.5.0)
+    minitest (5.25.1)
+    minitest-reporters (1.7.1)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
-    mocha (1.13.0)
+    mocha (2.4.5)
+      ruby2_keywords (>= 0.0.5)
     multipart-post (2.4.1)
     parallel (1.21.0)
     parser (3.1.1.0)
@@ -86,9 +87,9 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.1.4)
   byebug (~> 11.1.3)
-  minitest (~> 5.0)
-  minitest-reporters (~> 1.5.0)
-  mocha (~> 1.13.0)
+  minitest (~> 5.25)
+  minitest-reporters (~> 1.7)
+  mocha (~> 2.4)
   rake (~> 13.0.1)
   rubocop (~> 1.26.0)
   sapi-client-ruby!

README.md

@@ -6,7 +6,7 @@ modelspec for the API, which is used to generate a custom API class using Ruby
 metaprogramming
 
 _N.B. This respository's primary branch name has been updated, please see the
-[#important](#important) section below for more information._
+[Main branch](#main-branch) section below for more information._
 
 ## Usage
 
@@ -19,7 +19,7 @@ application's `Gemfile`:
 
 ```ruby
 source "https://rubygems.pkg.github.com/epimorphics" do
-  gem "sapi-client-ruby", "~> 1.0.0"
+  gem "sapi-client-ruby", "~> 1.2"
 end
 ```
 
@@ -51,16 +51,22 @@ about creating a PAT.
 To aid debugging and exploring a Sapi-NT endpoint, this library has a
 command-line tool `sapi`.  As required inputs, the tool needs both the base URL
 for the Sapi-NT API instance (e.g. `http://localhost:8080`), and the location of
-the Sapi-NT configuration root file. These can either be passed as command-line
-arguments, or as environment variables:
+the Sapi-NT modelspec files (see [Modelspec files](#modelspec-files) below).
+These can either be passed as command-line arguments, or as environment variables:
 
 ```sh
 sapi -b http://localhost:8080 -s test/fixtures/unified-view/application.yaml inspect
-
+```
+or
+```sh
 export SAPI_BASE_URL=http://localhost:8080
 export SAPI_SPEC_FILE=test/fixtures/unified-view/application.yaml
 sapi inspect
 ```
+or, using the endpoint specs directory
+```sh
+sapi -b http://localhost:8080 -s test/fixtures/unified-view/endpointSpecs inspect
+```
 
 See `sapi --help` for more details.
 
@@ -241,7 +247,9 @@ $ sapi establishment_item MBTM1R-A8K4VZ-2FJCYJ -j
 ### Using Sapi-client from code
 
 Create a new instance of the `SapiClient::Application`, initialised with the
-base URL and the location of the root YAML file for the application:
+base URL and either the location of the root YAML file for the application, or 
+the directory containing the endpoint specification YAML files (see [Modelspec 
+files](#modelspec-files) below).
 
 ```ruby
 irb(main):001:0> app = SapiClient::Application.new('http://localhost:8080', 'test/fixtures/unified-view/application.yaml')
@@ -286,7 +294,7 @@ resources.
 To associate the values of an endpoint with a facade class, there are a number
 of options:
 
-- a class may be be passed via the `wrapper` option when invoking an API
+- a class may be passed via the `wrapper` option when invoking an API
   endpoint method. E.g: `myEndpoint.establishment_list(_limit: 1, wrapper:
   MyClass)`
 - if no explicit `wrapper option is available`, the endpoint will look for a
@@ -349,7 +357,22 @@ The events emitted are:
 
 ## Developer notes
 
-### Important
+### Modelspec files
+
+Both `sapi-nt` and `sapi-client-ruby` are configured using a set of "modelspec"
+files that detail the endpoint URL templates, arguments and responses of a given 
+API.
+
+`sapi-nt` uses an `application.yaml` configuration file that, amongst other things, 
+points to the location of the directory of these modelspec (YAML) files, although 
+often these are resources in a JAR file, so use Java's classpath machinery.
+
+As a step away from too closely coupling `sapi-nt` and `sapi-client-ruby`, we now 
+additionally allow initialization of the `SapiClient::Application` using the 
+location of the directory containing the modelspec files, usually called 
+`endpointSpecs`.
+
+### Main branch
 
 If you have already cloned the repository to your local instance, you will need
 to run the following commands to update the primary branch name:

exe/sapi

@@ -7,12 +7,12 @@ require 'sapi_client'
 
 options = {
   base: ENV['SAPI_BASE_URL'],
-  spec: ENV['SAPI_SPEC_FILE']
+  spec: ENV['SAPI_SPEC_FILE'] || ENV['SAPI_SPEC']
 }
 
-def spec_file(options)
+def spec_file_or_dir(options)
   unless File.exist?(options[:spec])
-    puts "Could not find spec file #{options[:spec]}"
+    puts "Could not find spec file/directory #{options[:spec]}"
     exit(1)
   end
 
@@ -22,13 +22,13 @@ end
 def usage
   <<~USAGE
     Usage:
-    sapi [-b SAPI_BASE_URL] [-s SAPI_SPEC_FILE] inspect
-    sapi [-b SAPI_BASE_URL] [-s SAPI_SPEC_FILE] <endpoint-name>
+    sapi [-b SAPI_BASE_URL] [-s SAPI_SPEC] inspect
+    sapi [-b SAPI_BASE_URL] [-s SAPI_SPEC] <endpoint-name>
 
     Full list of options:
     sapi -h
 
-    Base URL and spec file can also be set as environment variables.
+    Base URL and spec file/dir can also be set as environment variables.
 
     v#{SapiClient::VERSION}
   USAGE
@@ -49,7 +49,7 @@ end
 
 def sapi_application(options)
   SapiClient::Application
-    .new(options.delete(:base), spec_file(options))
+    .new(options.delete(:base), spec_file_or_dir(options))
 end
 
 def inspect_sapi(options)
@@ -90,7 +90,8 @@ OptionParser.new do |parser|
     options[:base] = url
   end
 
-  parser.on('-s', '--spec-file SAPI_SPEC_FILE', 'The location of the specification file') do |file_name|
+  parser.on('-s', '--spec-file SAPI_SPEC',
+            'The directory with specification files, or location of sapi-nt application.yaml') do |file_name|
     options[:spec] = file_name
   end
 

lib/sapi_client/application.rb

@@ -5,14 +5,17 @@ module SapiClient
   # enclosed endpoint specifications to perform various operations, such as creating
   # methods we can call
   class Application
-    def initialize(base_url, application_spec)
-      unless File.exist?(application_spec)
-        raise(SapiError, "Could not find application spec #{application_spec}")
+    def initialize(base_url, application_or_endpoints)
+      unless File.exist?(application_or_endpoints)
+        raise(SapiError, "Could not find spec file/directory #{application_or_endpoints}")
       end
 
       @base_url = base_url
-      @application_spec_file = application_spec
-      @specification = YAML.load_file(application_spec)
+      @application_spec_file = File.file?(application_or_endpoints) ? application_or_endpoints : nil
+      @endpoints_path = File.directory?(application_or_endpoints) ? application_or_endpoints : nil
+      @specification = (@application_spec_file && YAML.load_file(application_or_endpoints)) || {
+        'sapi-nt' => { 'config' => { 'loadSpecPath' => 'classpath:endpointSpecs' } }
+      }
     end
 
     attr_reader :base_url, :specification
@@ -30,11 +33,15 @@ def application_spec_dir
     end
 
     def load_spec_path
-      configuration['loadSpecPath'].sub(/^classpath:/, '')
+      @endpoints_path || configuration['loadSpecPath'].sub(/^classpath:/, '')
     end
 
     def endpoint_group_files
-      Dir["#{application_spec_dir}/#{load_spec_path}/*.yaml"]
+      if @endpoints_path.nil?
+        Dir["#{application_spec_dir}/#{load_spec_path}/*.yaml"]
+      else
+        Dir["#{@endpoints_path}/*.yaml"]
+      end
     end
 
     def endpoints

lib/sapi_client/version.rb

@@ -2,7 +2,7 @@
 
 module SapiClient
   MAJOR = 1
-  MINOR = 1
-  FIX = 4
+  MINOR = 2
+  FIX = 0
   VERSION = "#{MAJOR}.#{MINOR}.#{FIX}"
 end

sapi-client-ruby.gemspec

@@ -36,9 +36,9 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler', '~> 2.1.4'
   spec.add_development_dependency 'byebug', '~> 11.1.3'
-  spec.add_development_dependency 'minitest', '~> 5.0'
-  spec.add_development_dependency 'minitest-reporters', '~> 1.5.0'
-  spec.add_development_dependency 'mocha', '~> 1.13.0'
+  spec.add_development_dependency 'minitest', '~> 5.25'
+  spec.add_development_dependency 'minitest-reporters', '~> 1.7'
+  spec.add_development_dependency 'mocha', '~> 2.4'
   spec.add_development_dependency 'rake', '~> 13.0.1'
   spec.add_development_dependency 'rubocop', '~> 1.26.0'
   spec.add_development_dependency 'simplecov', '~> 0.21.1'