sober_swag 0.18.0 → 0.22.0

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|
           [
@@ -33,7 +51,9 @@ module SoberSwag
               description: route.response_descriptions[status],
               content: {
                 'application/json': {
-                  schema: compiler.response_for(serializer.type)
+                  schema: compiler.response_for(
+                    serializer.respond_to?(:swagger_schema) ? serializer : serializer.type
+                  )
                 }
               }
             }
@@ -41,10 +61,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 +82,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 +94,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 +112,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,10 +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,
@@ -57,6 +72,8 @@ module SoberSwag
           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

@@ -13,10 +13,13 @@ module SoberSwag
     def initialize
       @types = Set.new
       @paths = Paths.new
+      @reporting_types = SoberSwag::Reporting::Compiler::Schema.new
     end
 
     ##
     # Convert a compiler to the overall type definition.
+    #
+    # @return Hash the swagger definition.
     def to_swagger
       {
         paths: path_schemas,
@@ -26,19 +29,32 @@ module SoberSwag
       }
     end
 
+    ##
+    # @return [SoberSwag::Reporting::Compiler::Schema]
+    attr_reader :reporting_types
+
     ##
     # 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
+      @types.map { |v| [v.ref_name, v.object_schema] }.to_h.merge(
+        reporting_types.references
+      )
     end
 
     ##
     # The path section of the swagger schema.
+    #
+    # @return [Hash]
     def path_schemas
       @paths.paths_list(self)
     end
@@ -46,60 +62,116 @@ 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
+      compiler = with_types_discovered(type)
+
+      if compiler.respond_to?(:swagger_path_schema)
+        compiler.swagger_path_schema
+      else
+        compiler.path_schema
+      end
     end
 
     ##
     # 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
+      compiler = with_types_discovered(type)
+
+      if compiler.respond_to?(:swagger_query_schema)
+        compiler.swagger_query_schema
+      else
+        compiler.query_schema
+      end
     end
 
     ##
     # 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)
+
+      return reporting_types.compile(type) if type.respond_to?(:swagger_schema)
+
       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
       tap do
-        type_compiler = Type.new(type)
+        if type.is_a?(SoberSwag::Reporting::Input::Interface) || type.is_a?(SoberSwag::Reporting::Output::Interface)
+          add_reporting_type(type)
+        else
+          add_dry_type(type)
+        end
+      end
+    end
 
-        ##
-        # Do nothing if we already have a type
-        return self if @types.include?(type_compiler)
+    private
 
-        @types.add(type_compiler) if type_compiler.standalone?
+    def add_dry_type(type)
+      type_compiler = Type.new(type)
 
-        type_compiler.found_types.each do |ft|
-          add_type(ft)
-        end
+      ##
+      # Do nothing if we already have a type
+      return self if @types.include?(type_compiler)
+
+      @types.add(type_compiler) if type_compiler.standalone?
+
+      type_compiler.found_types.each do |ft|
+        add_type(ft)
       end
     end
 
-    private
+    def add_reporting_type(type)
+      reporting_types.compile(type)
+    end
 
     def with_types_discovered(type)
+      if type.respond_to?(:swagger_schema)
+        with_reporting_types_discovered(type)
+      else
+        with_dry_types_discovered(type)
+      end
+    end
+
+    def with_reporting_types_discovered(type)
+      type.tap { |t| reporting_types.compile(t) }
+    end
+
+    def with_dry_types_discovered(type)
       Type.new(type).tap do |type_compiler|
         type_compiler.found_types.each { |ft| add_type(ft) }
       end