sober_swag 0.17.0 → 0.21.0

data/example/config/environments/production.rb

@@ -60,7 +60,7 @@ Rails.application.configure do
   # config.logger = ActiveSupport::TaggedLogging.new(Syslog::Logger.new 'app-name')
 
   if ENV['RAILS_LOG_TO_STDOUT'].present?
-    logger           = ActiveSupport::Logger.new(STDOUT)
+    logger           = ActiveSupport::Logger.new($stdout)
     logger.formatter = config.log_formatter
     config.logger    = ActiveSupport::TaggedLogging.new(logger)
   end

data/lib/sober_swag/compiler/path.rb

@@ -1,8 +1,11 @@
 module SoberSwag
   class Compiler
     ##
-    # Compile a singular path, and that's it.
-    # Only handles the actual body.
+    # This compiler transforms a {SoberSwag::Controller::Route} object into its associated OpenAPI V3 definition.
+    # These definitions are [called "paths" in the OpenAPI V3 spec](https://swagger.io/docs/specification/paths-and-operations/),
+    # thus the name of this compiler.
+    #
+    # It only compiles a *single* "path" at a time.
     class Path
       ##
       # @param route [SoberSwag::Controller::Route] a route to use
@@ -12,8 +15,18 @@ module SoberSwag
         @compiler = compiler
       end
 
-      attr_reader :route, :compiler
+      ##
+      # @return [SoberSwag::Controller::Route]
+      attr_reader :route
+
+      ##
+      # @return [SoberSwag::Compiler] the compiler used for type compilation
+      attr_reader :compiler
 
+      ##
+      # The OpenAPI V3 "path" object for the associated {SoberSwag::Controller::Route}
+      #
+      # @return [Hash] the OpenAPI V3 description
       def schema
         base = {}
         base[:summary] = route.summary if route.summary
@@ -25,6 +38,11 @@ module SoberSwag
         base
       end
 
+      ##
+      # An array of "response" objects from swagger.
+      #
+      # @return [Hash{String => Hash}]
+      #   response code to response object.
       def responses # rubocop:disable Metrics/MethodLength
         route.response_serializers.map { |status, serializer|
           [
@@ -41,10 +59,19 @@ module SoberSwag
         }.to_h
       end
 
+      ##
+      # An array of all parameters, be they in the query or in the path.
+      # See [this page](https://swagger.io/docs/specification/serialization/) for what that looks like.
+      #
+      # @return [Array<Hash>]
       def params
         query_params + path_params
       end
 
+      ##
+      # An array of schemas for all query parameters.
+      #
+      # @return [Array<Hash>] the schemas
       def query_params
         if route.query_params_class
           compiler.query_params_for(route.query_params_class)
@@ -53,6 +80,10 @@ module SoberSwag
         end
       end
 
+      ##
+      # An array of schemas for all path parameters.
+      #
+      # @return [Array<Hash>] the schemas
       def path_params
         if route.path_params_class
           compiler.path_params_for(route.path_params_class)
@@ -61,6 +92,11 @@ module SoberSwag
         end
       end
 
+      ##
+      # The schema for a request body.
+      # Matches [this spec.](https://swagger.io/docs/specification/paths-and-operations/)
+      #
+      # @return [Hash] the schema
       def request_body
         return nil unless route.request_body_class
 
@@ -74,6 +110,9 @@ module SoberSwag
         }
       end
 
+      ##
+      # The tags for this path.
+      # @return [Array<String>] the tags
       def tags
         return nil unless route.tags.any?
 

data/lib/sober_swag/compiler/paths.rb

@@ -2,15 +2,28 @@ module SoberSwag
   class Compiler
     ##
     # Compile multiple routes into a paths set.
+    # This basically just aggregates {SoberSwag::Controller::Route} objects.
     class Paths
+      ##
+      # Set up a new paths compiler with no routes in it.
       def initialize
         @routes = []
       end
 
+      ##
+      # Add on a new {SoberSwag::Controller::Route}
+      #
+      # @param route [SoberSwag::Controller::Route] the route description to add to compilation
+      # @return [SoberSwag::Compiler::Paths] self
       def add_route(route)
         @routes << route
+
+        self
       end
 
+      ##
+      # In the OpenAPI V3 spec, we group action definitions by their path.
+      # This helps us do that.
       def grouped_paths
         routes.group_by(&:path)
       end
@@ -20,6 +33,9 @@ module SoberSwag
       # paths list. Since this is only a compiler for paths,
       # it has *no idea* how to handle types. So, it takes a compiler
       # which it will use to do that for it.
+      #
+      # @param compiler [SoberSwag::Compiler::Type] the type compiler to use
+      # @return [Hash] a schema for all contained routes.
       def paths_list(compiler)
         grouped_paths.transform_values do |values|
           values.map { |route|
@@ -31,6 +47,8 @@ module SoberSwag
       ##
       # Get a list of all types we discovered when compiling
       # the paths.
+      #
+      # @yield [Class] all the types found in all the routes described in here.
       def found_types
         return enum_for(:found_types) unless block_given?
 
@@ -41,6 +59,8 @@ module SoberSwag
         end
       end
 
+      ##
+      # @return [Array<SoberSwag::Controller::Route>] the routes to document
       attr_reader :routes
 
       private

data/lib/sober_swag/compiler/primitive.rb

@@ -4,7 +4,11 @@ module SoberSwag
     # Compiles a primitive type.
     # Almost always constructed with the values from
     # {SoberSwag::Nodes::Primitive}.
+    #
+    # This works by either generating a swagger primitive definition, *or* a `$ref` to one with a given identifier.
     class Primitive
+      ##
+      # @param type [Class] the swagger-able class to document.
       def initialize(type)
         @type = type
 
@@ -13,6 +17,8 @@ module SoberSwag
 
       attr_reader :type
 
+      ##
+      # Is this documenting one of the build-in swagger types?
       def swagger_primitive?
         SWAGGER_PRIMITIVE_DEFS.include?(type)
       end
@@ -25,6 +31,9 @@ module SoberSwag
 
       ##
       # Turn this type into a swagger hash with a proper type key.
+      # This is suitable for use as the value of a `schema` key in a definition.
+      #
+      # @return [Hash] the schema.
       def type_hash
         if swagger_primitive?
           SWAGGER_PRIMITIVE_DEFS.fetch(type)
@@ -37,9 +46,16 @@ module SoberSwag
         end
       end
 
+      ##
+      # Primitive schema used for ruby `Date` values.
       DATE_PRIMITIVE = { type: :string, format: :date }.freeze
+      ##
+      # Primitive schema used for ruby `DateTime` values.
       DATE_TIME_PRIMITIVE = { type: :string, format: :'date-time' }.freeze
+      HASH_PRIMITIVE = { type: :object, additionalProperties: true }.freeze
 
+      ##
+      # Map of types that are considered "primitive types" in the OpenAPI V3 spec.
       SWAGGER_PRIMITIVE_DEFS =
         {
           NilClass => :null,
@@ -52,9 +68,12 @@ module SoberSwag
         .to_h.merge(
           Date => DATE_PRIMITIVE,
           DateTime => DATE_TIME_PRIMITIVE,
-          Time => DATE_TIME_PRIMITIVE
+          Time => DATE_TIME_PRIMITIVE,
+          Hash => HASH_PRIMITIVE
         ).transform_values(&:freeze).freeze
 
+      ##
+      # @return [String] the schema reference
       def ref_name
         raise Error, 'is not a type that is named!' if swagger_primitive?
 

data/lib/sober_swag/compiler/type.rb

@@ -1,45 +1,95 @@
 module SoberSwag
   class Compiler
     ##
-    # A compiler for DRY-Struct data types, essentially.
-    # It only consumes one type at a time.
+    # A compiler for swagger-able types.
+    #
+    # This class turns Swagger-able types into a *schema*.
+    # This Schema may be:
+    # - a [schema object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#schemaObject) with {#object_schema}
+    # - a [path schema](https://swagger.io/docs/specification/describing-parameters/#path-parameters) with {#path_schema}
+    # - a [query schema](https://swagger.io/docs/specification/describing-parameters/#query-parameters) with {#query_schema}
+    #
+    # As such, it compiles all types to all applicable schemas.
+    #
+    # While this class compiles *one* type at a time, it *keeps track* of the other types needed to describe this schema.
+    # It stores these types in a set, available at {#found_types}.
+    #
+    # For example, with a schema like:
+    #
+    # ```ruby
+    # class Bar < SoberSwag::InputObject
+    #   attribute :baz, primitive(:String)
+    # end
+    #
+    # class Foo < SoberSwag::InputObject
+    #   attribute :bar, Bar
+    # end
+    # ```
+    #
+    # If you compile `Foo` with this class, {#found_types} will include `Bar`.
+    #
     class Type # rubocop:disable Metrics/ClassLength
+      ##
+      # An error raised when a type is too complicated for a given schema.
+      # This may be due to containing too many layers of nesting.
       class TooComplicatedError < ::SoberSwag::Compiler::Error; end
+      ##
+      # An error raised when a type is too complicated to transform into a *path* schema.
       class TooComplicatedForPathError < TooComplicatedError; end
+      ##
+      # An error raised when a type is too complicated to transform into a *query* schema.
       class TooComplicatedForQueryError < TooComplicatedError; end
 
+      ##
+      # A list of acceptable keys to use as metadata for an object schema.
+      # All other metadata keys defined on a type with {SoberSwag::InputObject.meta} will be ignored.
+      #
+      # @return [Array<Symbol>] valid keys.
       METADATA_KEYS = %i[description deprecated].freeze
 
+      ##
+      # Create a new compiler for a swagger-able type.
+      # @param type [Class] the type to compile
       def initialize(type)
         @type = type
       end
 
+      ##
+      # @return [Class] the type we are compiling.
       attr_reader :type
 
       ##
       # Is this type standalone, IE, worth serializing on its own
       # in the schemas section of our schema?
+      # @return [true,false]
       def standalone?
         type.is_a?(Class)
       end
 
+      ##
+      # Get back the [schema object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#schemaObject)
+      # for the type described.
+      #
+      # @return [Hash]
       def object_schema
         @object_schema ||=
           make_object_schema
       end
 
-      def object_schema_meta
-        return {} unless standalone? && type <= SoberSwag::Type::Named
-
-        {
-          description: type.description
-        }.reject { |_, v| v.nil? }
-      end
-
+      ##
+      # Give a "stub type" for this schema.
+      # This is suitable to use as the schema for attributes of other schemas.
+      # Almost always generates a ref object.
+      # @return [Hash] the OpenAPI V3 schema stub
       def schema_stub
         @schema_stub ||= generate_schema_stub
       end
 
+      ##
+      # The schema for this type when it is path of the path.
+      #
+      # @raise [TooComplicatedForPathError] when the compiled type is too complicated to use in a path
+      # @return [Hash] a [path parameters hash](https://swagger.io/docs/specification/describing-parameters/#path-parameters) for this type.
       def path_schema
         path_schema_stub.map do |e|
           ensure_uncomplicated(e[:name], e[:schema])
@@ -51,16 +101,30 @@ module SoberSwag
 
       DEFAULT_QUERY_SCHEMA_ATTRS = { in: :query, style: :deepObject, explode: true }.freeze
 
+      ##
+      # The schema for this type when it is part of the query.
+      # @raise [TooComplicatedForQueryError] when this type is too complicated to use in a query schema
+      # @return [Hash] a [query parameters hash](https://swagger.io/docs/specification/describing-parameters/#query-parameters) for this type.
       def query_schema
         path_schema_stub.map { |e| DEFAULT_QUERY_SCHEMA_ATTRS.merge(e) }
       rescue TooComplicatedError => e
         raise TooComplicatedForQueryError, e.message
       end
 
+      ##
+      # Get the name of this type if it is to be used in a `$ref` key.
+      # This is useful if we are going to use this type compiler to compile an *attribute* of another object.
+      #
+      # @return [String] a reference specifier for this type
       def ref_name
         SoberSwag::Compiler::Primitive.new(type).ref_name
       end
 
+      ##
+      # Get a set of all other types needed to compile this type.
+      # This set will *not* include the type being compiled.
+      #
+      # @return [Set<Class>]
       def found_types
         @found_types ||=
           begin
@@ -69,32 +133,51 @@ module SoberSwag
           end
       end
 
-      def mapped_type
-        @mapped_type ||= parsed_type.map { |v| SoberSwag::Compiler::Primitive.new(v).type_hash }
-      end
-
-      def parsed_type
-        @parsed_type ||=
-          begin
-            (parsed,) = parsed_result
-            parsed
-          end
-      end
-
+      ##
+      # This type, parsed into an AST.
       def parsed_result
         @parsed_result ||= Parser.new(type_for_parser).run_parser
       end
 
+      ##
+      # Standard ruby equality.
       def eql?(other)
         other.class == self.class && other.type == type
       end
 
+      ##
+      # Standard ruby hashing method.
+      # Compilers hash to the same value if they are compiling the same type.
       def hash
         [self.class, type].hash
       end
 
       private
 
+      ##
+      # Get metadata attributes to be used if compiling an object schema.
+      #
+      # @return [Hash]
+      def object_schema_meta
+        return {} unless standalone? && type <= SoberSwag::Type::Named
+
+        {
+          description: type.description
+        }.reject { |_, v| v.nil? }
+      end
+
+      def parsed_type
+        @parsed_type ||=
+          begin
+            (parsed,) = parsed_result
+            parsed
+          end
+      end
+
+      def mapped_type
+        @mapped_type ||= parsed_type.map { |v| SoberSwag::Compiler::Primitive.new(v).type_hash }
+      end
+
       def generate_schema_stub
         if type.is_a?(Class)
           SoberSwag::Compiler::Primitive.new(type).type_hash

data/lib/sober_swag/compiler.rb

@@ -17,6 +17,8 @@ module SoberSwag
 
     ##
     # Convert a compiler to the overall type definition.
+    #
+    # @return Hash the swagger definition.
     def to_swagger
       {
         paths: path_schemas,
@@ -29,16 +31,23 @@ module SoberSwag
     ##
     # Add a path to be compiled.
     # @param route [SoberSwag::Controller::Route] the route to add.
+    # @return [Compiler] self
     def add_route(route)
       tap { @paths.add_route(route) }
     end
 
+    ##
+    # Get the schema of each object type defined in this Compiler.
+    #
+    # @return [Hash]
     def object_schemas
       @types.map { |v| [v.ref_name, v.object_schema] }.to_h
     end
 
     ##
     # The path section of the swagger schema.
+    #
+    # @return [Hash]
     def path_schemas
       @paths.paths_list(self)
     end
@@ -46,6 +55,9 @@ module SoberSwag
     ##
     # Compile a type to a new, path-params list.
     # This will add all subtypes to the found types list.
+    #
+    # @param type [Class] the type to get a path_params definition for
+    # @return [Hash]
     def path_params_for(type)
       with_types_discovered(type).path_schema
     end
@@ -53,6 +65,9 @@ module SoberSwag
     ##
     # Get the query params list for a type.
     # All found types will be added to the reference dictionary.
+    #
+    # @param type [Class] the type to get the query_params definitions for
+    # @return [Hash]
     def query_params_for(type)
       with_types_discovered(type).query_schema
     end
@@ -60,25 +75,36 @@ module SoberSwag
     ##
     # Get the request body definition for a type.
     # This will always be a ref.
+    #
+    # @param type [Class] the type to get the body definition for
+    # @return [Hash]
     def body_for(type)
       add_type(type)
       Type.new(type).schema_stub
     end
 
     ##
-    # Get the definition of a response type
+    # Get the definition of a response type.
+    #
+    # This is an alias of {#body_for}
+    # @see body_for
     def response_for(type)
       body_for(type)
     end
 
     ##
-    # Get the existing schema for a given type
+    # Get the existing schema for a given type.
+    #
+    # @param type [Class] the type to get the schema for
+    # @return [Hash,nil] the swagger schema for this object, or nil if it was not found.
     def schema_for(type)
       @types.find { |type_comp| type_comp.type == type }&.object_schema
     end
 
     ##
-    # Add a type in the types reference dictionary, essentially
+    # Add a type in the types reference dictionary, essentially.
+    # @param type [Class] the type to compiler
+    # @return [SoberSwag::Compiler] self
     def add_type(type)
       # use tap here to avoid an explicit self at the end of this
       # which makes this method chainable