brainstem 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9abf1184c78ea43d4e00ae5aa6f2a11fdb663013
-  data.tar.gz: 421ffc9a7dd8cce73ad64bcadd40a4108b79c7bf
+  metadata.gz: e825c08d783b4cecd7da03879db5545efd3e0697
+  data.tar.gz: 1478c23f3186dd7d065585d102245e995e6d9df5
 SHA512:
-  metadata.gz: 8a230a3bbe9bee9643bc96a6b894a8e86669483b1057cb6d7131a3c0ed34817b81739bb1cdc8bc15e64d6c3ca50a84a947133cb68bf3ebbdea702769f5542f59
-  data.tar.gz: 0b20e2fc89ce9d3b5ac655b959ca56779d37fc2c22ed2e229666d65925932a46fae573e1ef56b7c15ead24c5fe1d8b8e4109523b531d2c273ee9eecc45549e81
+  metadata.gz: 27a6f03a61dcd1371ffe0b7860563fe8ba94b6be14814f21ae35f4230d2af65fdcf1790f8a547c5913d11611a4ded52e8f17136cd6b6efb4d8a32adf40b1680c
+  data.tar.gz: 501e3164fade58216384cc7ddfe32a07e009af99029a75ddd0f1db19d770e356983af1d4786953997ff18ce3ea03a55e376db05a784db06088e0e3090b131b84

data/CHANGELOG.md

@@ -1,5 +1,151 @@
 # Changelog
 
++ **2.1.0** - _05/10/2019_
+  ### New Features
+    - Add the ability to mark properties as internal for Open API.
+    ```ruby
+    class ContactsController < ApiController
+      internal! "Only used internally"
+
+      brainstem_params do
+        actions :index do
+          response :hash do
+            field :count, :integer,
+                  info: "Total count of contacts",
+                  internal: "Internal eyes only"
+            fields :contacts, :array,
+                   item_type: :hash,
+                   nodoc: true,
+                   info: "Array of contact details" do
+              field :full_name, :string,
+                    info: "Full name of the contact",
+                    internal: true
+            end
+          end
+        end
+      end
+    end
+    ```
+    
+    - Add `--include-internal` option to CLI:
+      `brainstem generate --include-internal --open-api-specification=2` will generate documentation for
+      everything that is not marked as `nodoc`.
+    
+    - Automatically generate documentation for associations
+      - `response_key` will be used if given, otherwise, it will use the name of the association appended
+        with `_id` or `_ids` for `has_many`.
+
+        Using the example below, the association for `PetCategory` will generate documentation for `shooby_id`,
+        while the `Owner` association will generate documentation for `owner_id`.
+      - The response will include references to all of the associations, including any `polymorphic_classes` added to
+        polymorphic associations.
+
+        In the example below, the documentation for the response will contain references to `PetCategory`, `Vaccine`,
+        `Owner`, `Dog`, and `Cat`.
+
+    ```ruby
+    class PetsPresenter < Brainstem::Presenter
+      presents Pet
+
+      associations do
+        association :pet_category, PetCategory,
+                    response_key: :shooby_id,
+                    type: :belongs_to
+        association :vaccines, Vaccine,
+                    response_key: :vaccine_ids,
+                    type: :has_many
+        association :owner, Owner,
+                    response_key: :owner_id,
+                    type: :has_one
+        association :pettable, :polymorphic,
+                    response_key: :pettable_ref,
+                    polymorphic_classes: [Dog, Cat]
+      end
+    end
+    ```
+
+    - Add support for non-static key fields in responses. When key is non-static, use the new DSL for response params.
+      See example below for usage.
+
+       ```ruby
+        {
+            :attributes => {
+                :"#{name}_field" => 'world',
+                :"#{name}_ids" => [1, 2, 3],
+                :name => name
+            },
+            :"#{model.class_name}_klass" => {
+                :"#{model.class_name}_identifier" => model.identifier,
+                :"#{model.association_name}_ids" => [1, 2, 3]
+            }
+        }
+       ```
+
+       A response with non-static key fields written above can be described as follows:
+
+       ```ruby
+       class ContactsController < ApiController
+         brainstem_params do
+           actions :show do
+             response :hash do |response_param|
+               response_param.fields :attributes, :hash do |attributes|
+                 attributes.dynamic_key_field :string
+                 attributes.field :some_ids, :array, dynamic: true
+                  attributes.field :name, :string, required: true
+               end
+
+               response_param.dynamic_key_field :hash do |dk|
+                 dk.dynamic_key_field :string
+                 dk.field :other_ids, :array, dynamic: true
+               end
+             end
+           end
+         end
+       end
+       ```
+
+    - Add support for non-static key params. When key is non-static, use the new DSL for request params.
+      See example below for usage.
+
+      A param with non-static keys like `{ contact.id => 10, :"#{contact.friends_association_name}_ids" => [1, 2, 3] }`
+      can be described as follows:
+
+      ```ruby
+      class ContactsController < ApiController
+        brainstem_params do
+          actions :create do
+            valid :info, :hash, required: true do |param|
+              param.valid_dynamic_param :integer, required: true
+              param.valid :some_ids, :array, dynamic: true
+            end
+          end
+        end
+      end
+      ```
+
+    - Sort orders now default to directions `asc` and `desc`.
+      When direction is passed as false, no sort order is generated for the docs.
+      - ex.
+        ```ruby
+          presenter_class.sort_order :created_at, value, info: "sorts by creation time", direction: false
+        ```
+
+    - Add new DSL for nested arrays
+      ```ruby
+        response :array, nested_level: 2, item_type: :hash do
+          nested.field :a, :string
+          nested.field :b, :integer
+        end
+      ```
+      - An example of the response above: `[[{a: "string", b: 1}, "another string", 4]]`
+
+  ### Bugfixes
+    - Nested required fields will now no longer bubble up the required to its parent. A deeply nested field that is 
+    required will now only be required on its direct parent.
+    - Required fields for a create / update (POST / PUT) request are explicitly called out in the OAS specification
+    - Default top-level query params like `only `, `order `, `page`, `per_page`, `include` & `optional` are not
+    displayed when the endpoint is not returning brainstem models.
+
 + **2.0.0** - _05/17/2018_
   - Introduce the capability to document custom response on endpoints
   ```ruby
@@ -20,6 +166,7 @@
         end
       end
     end
+  end
   ```
   - Add DSL on controllers to set Open API Specification 2.0 configurations
   ```ruby

data/Gemfile.lock

@@ -1,70 +1,99 @@
 PATH
   remote: .
   specs:
-    brainstem (1.4.1)
+    brainstem (2.2.0)
       activerecord (>= 4.1)
       activesupport (>= 4.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (5.1.4)
-      activesupport (= 5.1.4)
-    activerecord (5.1.4)
-      activemodel (= 5.1.4)
-      activesupport (= 5.1.4)
-      arel (~> 8.0)
-    activesupport (5.1.4)
+    actionpack (5.2.3)
+      actionview (= 5.2.3)
+      activesupport (= 5.2.3)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.3)
+      activesupport (= 5.2.3)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activemodel (5.2.3)
+      activesupport (= 5.2.3)
+    activerecord (5.2.3)
+      activemodel (= 5.2.3)
+      activesupport (= 5.2.3)
+      arel (>= 9.0)
+    activesupport (5.2.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (~> 0.7)
+      i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    arel (8.0.0)
+    arel (9.0.0)
+    builder (3.2.3)
     coderay (1.1.2)
-    concurrent-ruby (1.0.5)
-    database_cleaner (1.6.1)
+    concurrent-ruby (1.1.5)
+    crass (1.0.4)
+    database_cleaner (1.7.0)
     db-query-matchers (0.9.0)
       activesupport (>= 4.0, <= 6.0)
       rspec (~> 3.0)
     diff-lcs (1.3)
-    i18n (0.9.0)
+    erubi (1.8.0)
+    i18n (1.6.0)
       concurrent-ruby (~> 1.0)
-    method_source (0.9.0)
-    minitest (5.10.3)
+    loofah (2.2.3)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (0.9.2)
+    mini_portile2 (2.4.0)
+    minitest (5.11.3)
     mysql2 (0.4.10)
-    pry (0.9.12.6)
-      coderay (~> 1.0)
-      method_source (~> 0.8)
-      slop (~> 3.4)
-    pry-nav (0.2.4)
-      pry (>= 0.9.10, < 0.11.0)
-    rake (12.2.1)
-    redcarpet (3.4.0)
+    nokogiri (1.10.3)
+      mini_portile2 (~> 2.4.0)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    pry-nav (0.3.0)
+      pry (>= 0.9.10, < 0.13.0)
+    rack (2.0.7)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.1.0)
+      loofah (~> 2.2, >= 2.2.2)
+    rake (12.3.3)
+    redcarpet (3.5.0)
     rr (1.2.1)
-    rspec (3.7.0)
-      rspec-core (~> 3.7.0)
-      rspec-expectations (~> 3.7.0)
-      rspec-mocks (~> 3.7.0)
-    rspec-core (3.7.0)
-      rspec-support (~> 3.7.0)
-    rspec-expectations (3.7.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.2)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.4)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-mocks (3.7.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-support (3.7.0)
-    slop (3.6.0)
-    sqlite3 (1.3.13)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.2)
+    sqlite3 (1.4.1)
     thread_safe (0.3.6)
-    tzinfo (1.2.4)
+    tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    yard (0.9.9)
+    yard (0.9.20)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  actionpack
   brainstem!
   database_cleaner
   db-query-matchers
@@ -79,4 +108,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   1.13.6
+   1.17.3

data/lib/brainstem/api_docs.rb

@@ -141,7 +141,7 @@ module Brainstem
     FORMATTERS = {
 
       # Formatter for entire response
-      document:    {},
+      document: {},
 
       # Formatters for collections
       controller_collection: {},
@@ -149,9 +149,9 @@ module Brainstem
       presenter_collection:  {},
 
       # Formatters for individual entities
-      controller:  {},
-      endpoint:    {},
-      presenter:   {},
+      controller: {},
+      endpoint:   {},
+      presenter:  {},
 
       # Formatter for Open API Specifications
       info:       {},
@@ -159,6 +159,11 @@ module Brainstem
       parameters: {},
       security:   {},
       tags:       {},
+
+      # Formatter for Open API Specifications Individual field / param definition
+      endpoint_param:  {},
+      presenter_field: {},
+      response_field:  {},
     }
   end
 end

data/lib/brainstem/api_docs/atlas.rb

@@ -18,9 +18,9 @@ module Brainstem
       include Concerns::Optional
 
       def initialize(introspector, options = {})
-        self.endpoints          = EndpointCollection.new(self)
-        self.controllers        = ControllerCollection.new(self)
-        self.presenters         = ::Brainstem::ApiDocs::PresenterCollection.new(self)
+        self.endpoints          = EndpointCollection.new(self, options)
+        self.controllers        = ControllerCollection.new(self, options)
+        self.presenters         = ::Brainstem::ApiDocs::PresenterCollection.new(self, options)
         self.resolver           = Resolver.new(self)
 
         self.controller_matches = []

data/lib/brainstem/api_docs/controller.rb

@@ -22,7 +22,8 @@ module Brainstem
                     :name,
                     :endpoints,
                     :filename_pattern,
-                    :atlas
+                    :atlas,
+                    :include_internal
 
       attr_writer   :filename_pattern,
                     :filename_link_pattern
@@ -33,7 +34,8 @@ module Brainstem
           :name,
           :formatters,
           :filename_pattern,
-          :filename_link_pattern
+          :filename_link_pattern,
+          :include_internal
         ]
       end
 
@@ -77,7 +79,7 @@ module Brainstem
       end
 
       def nodoc?
-        default_configuration[:nodoc]
+        nodoc_for?(default_configuration)
       end
 
       def title
@@ -101,13 +103,19 @@ module Brainstem
       #
       def contextual_documentation(key)
         default_configuration.has_key?(key) &&
-          !default_configuration[key][:nodoc] &&
+          !nodoc_for?(default_configuration[key]) &&
           default_configuration[key][:info]
       end
 
       def valid_sorted_endpoints
         endpoints.sorted_with_actions_in_controller(const)
       end
+
+      private
+
+      def nodoc_for?(config)
+        !!(config[:nodoc] || (config[:internal] && !include_internal))
+      end
     end
   end
 end

data/lib/brainstem/api_docs/controller_collection.rb

@@ -5,13 +5,22 @@ module Brainstem
   module ApiDocs
     class ControllerCollection < AbstractCollection
 
+      attr_accessor :include_internal
+
+      def valid_options
+        super | [
+          :include_internal
+        ]
+      end
+
       #
       # Creates a new controller from a route object and appends it to the
       # collection.
       def create_from_route(route)
         Controller.new(atlas,
-          const:  route[:controller],
-          name:   route[:controller_name].split("/").last
+          const:            route[:controller],
+          name:             route[:controller_name].split("/").last,
+          include_internal: include_internal
         ).tap { |controller| self.<< controller }
       end
 

data/lib/brainstem/api_docs/endpoint.rb

@@ -23,7 +23,8 @@ module Brainstem
           :controller,
           :controller_name,
           :action,
-          :presenter
+          :presenter,
+          :include_internal
         ]
       end
 
@@ -38,7 +39,8 @@ module Brainstem
                     :controller,
                     :controller_name,
                     :action,
-                    :atlas
+                    :atlas,
+                    :include_internal
 
       #
       # Pretty prints each endpoint.
@@ -94,7 +96,7 @@ module Brainstem
       # Is the entire endpoint undocumentable?
       #
       def nodoc?
-        action_configuration[:nodoc]
+        nodoc_for?(action_configuration)
       end
 
       def title
@@ -156,7 +158,8 @@ module Brainstem
             .with_indifferent_access
             .inject(ActiveSupport::HashWithIndifferentAccess.new) do |result, (field_name_proc, field_config)|
 
-            next result if field_config[:nodoc]
+            next result if nodoc_for?(field_config)
+            field_config = field_config.except(:nodoc, :internal)
 
             field_name = evaluate_field_name(field_name_proc)
             if field_config.has_key?(:ancestors)
@@ -199,7 +202,8 @@ module Brainstem
             .except(:_config)
             .inject(custom_config_tree) do |result, (field_name_proc, field_config)|
 
-            next result if field_config[:nodoc]
+            next result if nodoc_for?(field_config)
+            field_config = field_config.except(:nodoc, :internal)
 
             field_name = evaluate_field_name(field_name_proc)
             if field_config.has_key?(:ancestors)
@@ -243,7 +247,7 @@ module Brainstem
       #
       def declared_presented_class
         valid_presents.has_key?(:target_class) &&
-          !valid_presents[:nodoc] &&
+          !nodoc_for?(valid_presents) &&
           valid_presents[:target_class]
       end
 
@@ -281,7 +285,7 @@ module Brainstem
       #
       def contextual_documentation(key)
         action_configuration.has_key?(key) &&
-          !action_configuration[key][:nodoc] &&
+          !nodoc_for?(action_configuration[key]) &&
           action_configuration[key][:info]
       end
 
@@ -305,6 +309,12 @@ module Brainstem
           presenter_path.relative_path_from(controller_path).to_s
         end
       end
+
+      private
+
+      def nodoc_for?(config)
+        !!(config[:nodoc] || (config[:internal] && !include_internal))
+      end
     end
   end
 end