dry_crud_jsonapi_swagger 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 807ceabf80b721ba30a118e1329834c7d3bbd59b01a3cda459ff9f1988c147bb
-  data.tar.gz: e004fe507b0d66740bd4123e59e53cede709043dc0837397ba655ae40cbc288f
+  metadata.gz: c9d805f02243eba631d4656adc5a7d7570367c11cdf7833f998d9beaf37336e6
+  data.tar.gz: 76ff302864cd450f719890d3742c547ac995177f7174ce0f04727176d4cae6a6
 SHA512:
-  metadata.gz: 91ad6961a51fbcf661c1bc719dd9f9d7d3b69a3c3f92320cf9b31b54532261eefab8f276f674fb724be976d670995ebc6611447b20f6e97cd3fb50e18cf65fc7
-  data.tar.gz: 0d59851eb55a49cbe99a39f15839e5d06ac48e5b0f8cf14c5eae9bee2ef61303b981e42027bf65aef72ad3c7fd7d5acda557b5bed1f51cefc782bada597846f2
+  metadata.gz: 9f6a9025c590e41addc7fe4fba525c97632ea10f6acb60d336a6d592d47bb5ff2ad4103a53d871eabb8f31dc8ebf5712f8433c94653fa6ca66a7cda7a1c877ab
+  data.tar.gz: b7e56393467e77e5979b0d3d958bb739c9befb8de9a1c5197a8795c245eac5f53973fed6b925ffa205f44c5c0c83ca37eb91d94c265732be8716221be75fca60

data/README.md

@@ -1,8 +1,6 @@
 # DryCrudJsonapiSwagger
-Short description and motivation.
-
-## Usage
-How to use my plugin.
+This Gem provides a Rails Engine to generate the api documentation for Applications based on [`dry_crud_jsonapi`].
+The documentation is exposed as a swagger v2 specification and can be viewed with the included, interactive swagger web interface.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -21,8 +19,20 @@ Or install it yourself as:
 $ gem install dry_crud_jsonapi_swagger
 ```
 
+## Usage
+* Implement the `json:api` in your application with [`dry_crud_jsonapi`]
+* Mount the engine in your `routes.rb`:
+
+      mount DryCrudJsonapiSwagger::Engine => '/apidocs'
+      
+The swagger webinterface is available on the mount path, i.e. `/apidocs`.
+To get the swagger v2 specification, just add `/swagger.json` to the mount path, i.e. `/apidocs/swagger.json`.
+
 ## Contributing
 Contribution directions go here.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+
+[`dry_crud_jsonapi`]: https://github.com/puzzle/dry_crud_jsonapi

data/app/controllers/dry_crud_jsonapi_swagger/apidocs_controller.rb

@@ -24,8 +24,8 @@ module DryCrudJsonapiSwagger
     end
 
     def json_api_controllers
-      ListController.descendants.select { |model| model.include?(DryCrudJsonapi) }.select do |controller|
-        controller.model_class rescue false
+      ActionController::Base.descendants.select do |controller|
+        controller.include?(DryCrudJsonapi) && controller&.model_class.present?
       end
     end
   end

data/app/domain/dry_crud_jsonapi_swagger/helper.rb

@@ -37,21 +37,20 @@ module DryCrudJsonapiSwagger
       nested_class.model_class.model_name
     end
 
-    def description(controller = controller_class)
-      # relationships = controller.model_class
-      #   .reflect_on_all_associations(:belongs_to)
-      #   .map(&:name).sort
-      #
-      # relationships += controller.model_class
-      # .reflect_on_all_associations(:has_many)
-      # .map(&:name).sort
+    def include_description(controller = controller_class)
+      <<~DESC
+        Available primary relations:
+        #{includes(controller.model_class).map { |inc| "* #{inc}" }.join("\n")}
 
-      relationships = controller.model_class
-        .reflect_on_all_associations
-        .map(&:name).sort
+        Separate values with a comma
 
-      'The following relationships are available: ' \
-        "#{relationships.join(', ')} (separate values with a comma)"
+        To include sub-relations, specify the relationship chain with the elements separated by '.'
+        i.e. "employee.address.town"
+      DESC
+    end
+
+    def includes(model_class)
+      model_class.reflect_on_all_associations.reject(&:polymorphic?).map(&:name).sort
     end
 
     def path_spec(swagger_doc, helper, type) # rubocop:disable Metrics/MethodLength
@@ -64,7 +63,7 @@ module DryCrudJsonapiSwagger
 
       swagger_doc.operation :get do
         key :summary, summary
-        helper.setup_tags(self)
+        helper.setup_tag(self)
         helper.parameters(self, helper, type)
         response 200 do
           key :description, summary + ' Response'
@@ -73,16 +72,17 @@ module DryCrudJsonapiSwagger
       end
     end
 
-    def setup_tags(swagger_doc)
-      swagger_doc.key :tags, [
-        'All',
-        TagsSetup.path_tag(@path)
-      ]
+    def setup_tag(swagger_doc)
+      tag = TagsSetup.new.path_tag(@path)
+      swagger_doc.key :tags, [tag] if tag.present?
     end
 
     def parameters(swagger_doc, helper, type)
       case type.to_sym
-      when :show, :nested then parameter_id swagger_doc, helper
+      when :index
+        parameter_custom swagger_doc, type
+      when :show, :nested
+        parameter_id swagger_doc, helper
       end
 
       parameter_include swagger_doc, helper, type
@@ -100,15 +100,32 @@ module DryCrudJsonapiSwagger
 
     def parameter_include(swagger_doc, helper, type) # rubocop:disable Metrics/MethodLength
       desc = case type.to_sym
-             when :index, :show then description
-             when :nested       then description helper.nested_class
+               when :index, :show then include_description
+               when :nested       then include_description(helper.nested_class)
              end
       swagger_doc.parameter do
-        key :name,        :include
-        key :in,          :query
-        key :description, desc
-        key :required,    false
-        key :type,        :string
+        key :name,             :include
+        key :in,               :query
+        key :description,      desc
+        key :required,         false
+        key :type,             :array
+        key :collectionFormat, :csv
+        items do
+          key :type, :string
+        end
+      end
+    end
+
+    def parameter_custom(swagger_doc, type)
+      controller_class.swagger_params[type].each do |param|
+        swagger_doc.parameter do
+          key :name,        param.name
+          key :in,          :query
+          key :description, param.description
+          key :required,    param.required
+          key :type,        param.type
+          key :enum,        param.enum if param.enum.present?
+        end
       end
     end
 
@@ -126,4 +143,4 @@ module DryCrudJsonapiSwagger
       end
     end
   end
-end
+end

data/app/domain/dry_crud_jsonapi_swagger/tags_setup.rb

@@ -1,3 +1,5 @@
+require 'yaml'
+
 module DryCrudJsonapiSwagger
   class TagsSetup
 
@@ -9,37 +11,46 @@ module DryCrudJsonapiSwagger
       setup_tags
     end
 
-    def self.path_tag(path)
-      new.get_tag_by_path(path)
+    def path_tag(path)
+      customized_tag(path) || derived_tag(path)
     end
 
-    def get_tag_by_path(path)
-      tags.each do |tag|
-        next if tag['include'].blank?
+    private
 
-        tag['include'].each do |inc|
-          return tag['name'] if path =~ /#{inc}/i
-        end
+    def customized_tag(path)
+      customized_tags.each do |tag|
+        next if tag['include'].blank?
 
+        return tag['name'] if tag['include'].any? { |inc| path =~ /#{inc}/i }
       end
+      
+      nil
     end
 
-    private
-
+    def derived_tag(path)
+      path.gsub(%r(/{[^}]+}), '').gsub('/', ' ').strip.titleize
+    end
 
     def setup_tags
-      tags.each do |tag|
+      customized_tags.each do |tag|
         @swagger_doc.tags tag.slice('name', 'description', 'externalDocs')
       end
     end
 
-    def tags
-      @tags ||= load_tags['tags']
+    def customized_tags
+      @customized_tags ||= load_customized_tags
     end
 
-    def load_tags
-      require 'yaml'
-      YAML.load_file(Rails.root.join('config', 'swagger-tags.yml')) # TODO: what is this for? fill yml with sensible values
+    def load_customized_tags
+      return [] unless File.exist?(Rails.root.join('config', 'swagger-tags.yml'))
+
+      YAML.load_file(Rails.root.join('config', 'swagger-tags.yml')).yield_self do |tags_data|
+        raise('Your config/swagger-tags.yml contains malformed data') unless
+          Array.wrap(tags_data&.keys).include?('tags') &&
+          Array.wrap(tags_data['tags']).all? { |tag| tag.is_a?(Hash) }
+
+        Array.wrap(tags_data['tags'])
+      end
     end
   end
-end
+end

data/lib/dry_crud_jsonapi_swagger.rb

@@ -1,5 +1,17 @@
 require "dry_crud_jsonapi_swagger/engine"
+require "dry_crud_jsonapi_swagger/param"
 
 module DryCrudJsonapiSwagger
-  # Your code goes here...
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :swagger_params, instance_writer: false
+    self.swagger_params = Hash.new { |hash, key| hash[key] = [] }
+  end
+
+  class_methods do
+    def swagger_param(action, name, type: type, description: nil, required: false, enum: nil)
+      swagger_params[action.to_sym] << Param.new(name, type, description, required, enum)
+    end
+  end
 end

data/lib/dry_crud_jsonapi_swagger/param.rb

@@ -0,0 +1,3 @@
+module DryCrudJsonapiSwagger
+  Param = Struct.new(:name, :type, :description, :required, :enum)
+end

data/lib/dry_crud_jsonapi_swagger/version.rb

@@ -1,3 +1,3 @@
 module DryCrudJsonapiSwagger
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry_crud_jsonapi_swagger
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniel Illi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-17 00:00:00.000000000 Z
+date: 2019-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -99,6 +99,7 @@ files:
 - config/routes.rb
 - lib/dry_crud_jsonapi_swagger.rb
 - lib/dry_crud_jsonapi_swagger/engine.rb
+- lib/dry_crud_jsonapi_swagger/param.rb
 - lib/dry_crud_jsonapi_swagger/version.rb
 homepage: https://rubygems.org/gems/dry_crud_jsonapi_swagger
 licenses: