apigen 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d490568fbf42afb3f2c5ee580739f02bf13403444c0c852004d44b9dc6a1c209
-  data.tar.gz: be1468d137a7efcee80ab31f496a7ffe74bd7eb09cdcf7514e8d569a79789d15
+  metadata.gz: d6432dfded34004dd760e36e95f01fba2714a01184cee2f5fa2d3de2f77c56e1
+  data.tar.gz: 4f5548567d427df026ca5ccdd73758ad2fde6115bc52c48785c32bd2527293c8
 SHA512:
-  metadata.gz: 4f55e4d77ef95e85938b51306fa0f0cc09ec5d6371eff815d50033760bed8a792d525bd2e7439dbec4eb324022ca88c176cd30b9674db2920d5bfd29a4e3ce4e
-  data.tar.gz: 6b2fc1dfc6ab532aa69ceb4d0c6d2c6143d7604bfd0002fe1317209ef245842e12fc620a508ea72edc69049307f43a455048f26836f812c327c354e38a32de42
+  metadata.gz: ef5b8bad5d1568dbdcca3737eae32ca85bf2be0e9286dc4ab55a7b6a9157b98f8d18a1be570365387e0196ab05aeb34dfab58578b122517f06357b27e0af8cdf
+  data.tar.gz: 067d66a73b3353443fc1b37c15b0912f14ae7a8be3ef081ef2ff8be7cf466f9703267415f4e4d88bc14355ce64ef43d4d487a42f35fc886f3ab75cee671fb488

data/lib/apigen/formats/json_base.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Apigen
+  module Formats
+    ##
+    # JsonBase contains the common logic for API declaration formats based on JSON Schema,
+    # such as JSON Schema itself, Swagger and OpenAPI.
+    module JsonBase
+      private
+
+      def definitions(api)
+        hash = {}
+        api.models.each do |key, model|
+          hash[key.to_s] = schema(api, model.type, model.description, model.example)
+        end
+        hash
+      end
+
+      def schema(api, type, description = nil, example = nil)
+        schema = schema_without_description(api, type)
+        schema['description'] = description unless description.nil?
+        schema['example'] = example unless example.nil?
+        schema
+      end
+
+      def schema_without_description(api, type)
+        case type
+        when Apigen::ObjectType
+          object_schema(api, type)
+        when Apigen::ArrayType
+          array_schema(api, type)
+        when Apigen::OneofType
+          oneof_schema(type)
+        when Apigen::EnumType
+          enum_schema(type)
+        when Apigen::PrimaryType
+          primary_schema(type)
+        when Apigen::ReferenceType
+          reference_schema(type)
+        else
+          raise "Unsupported type: #{type}."
+        end
+      end
+
+      def object_schema(api, object_type)
+        {
+          'type' => 'object',
+          'properties' => object_type.properties.map { |name, property| object_property(api, name, property) }.to_h,
+          'required' => object_type.properties.select { |_name, property| property.required? }.map { |name, _property| name.to_s }
+        }
+      end
+
+      def object_property(api, name, property)
+        [name.to_s, schema(api, property.type, property.description, property.example)]
+      end
+
+      def array_schema(api, array_type)
+        {
+          'type' => 'array',
+          'items' => schema(api, array_type.type)
+        }
+      end
+
+      def oneof_schema(oneof_type)
+        schema = {
+          'oneOf' => oneof_type.mapping.keys.map { |model_name| { '$ref' => model_ref(model_name) } }
+        }
+        if supports_discriminator? && oneof_type.discriminator
+          schema['discriminator'] = {
+            'propertyName' => oneof_type.discriminator.to_s,
+            'mapping' => oneof_type.mapping.map { |model_name, disc_value| [disc_value, model_ref(model_name)] }.to_h
+          }
+        end
+        schema
+      end
+
+      def enum_schema(enum_type)
+        {
+          'type' => 'string',
+          'enum' => enum_type.values
+        }
+      end
+
+      def primary_schema(primary_type)
+        case primary_type.shape
+        when :string
+          {
+            'type' => 'string'
+          }
+        when :int32
+          {
+            'type' => 'integer',
+            'format' => 'int32'
+          }
+        when :bool
+          {
+            'type' => 'boolean'
+          }
+        else
+          raise "Unsupported primary type :#{primary_type.shape}."
+        end
+      end
+
+      def reference_schema(reference_type)
+        { '$ref' => model_ref(reference_type.model_name) }
+      end
+    end
+  end
+end

data/lib/apigen/formats/jsonschema.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require_relative './json_base'
 
 module Apigen
   module Formats
@@ -9,72 +10,23 @@ module Apigen
       # JSON Schema Draft 7 generator.
       module Draft7
         class << self
-          def generate(api)
-            JSON.pretty_generate definitions(api)
-          end
-
-          private
+          include Apigen::Formats::JsonBase
 
-          def definitions(api)
-            {
+          def generate(api)
+            JSON.pretty_generate(
               '$schema' => 'http://json-schema.org/draft-07/schema#',
-              'definitions' => api.models.map { |key, model| [key.to_s, schema(api, model.type, model.description, model.example)] }.to_h
-            }
+              'definitions' => definitions(api)
+            )
           end
 
-          def schema(api, type, description = nil, example = nil)
-            schema = schema_without_description(api, type)
-            schema['description'] = description unless description.nil?
-            schema['example'] = example unless example.nil?
-            schema
-          end
-
-          def schema_without_description(api, type)
-            case type
-            when Apigen::ObjectType
-              object_schema(api, type)
-            when Apigen::ArrayType
-              array_schema(api, type)
-            when Apigen::OptionalType
-              raise 'OptionalType fields are only supported within object types.'
-            when :string
-              {
-                'type' => 'string'
-              }
-            when :int32
-              {
-                'type' => 'integer',
-                'format' => 'int32'
-              }
-            when :bool
-              {
-                'type' => 'boolean'
-              }
-            else
-              return { '$ref' => "#/definitions/#{type}" } if api.models.key? type
-              raise "Unsupported type: #{type}."
-            end
-          end
-
-          def object_schema(api, object_type)
-            {
-              'type' => 'object',
-              'properties' => object_type.properties.map { |name, property| object_property(api, name, property) }.to_h,
-              'required' => object_type.properties.reject { |_name, property| property.type.is_a? Apigen::OptionalType }.map { |name, _property| name.to_s }
-            }
-          end
+          private
 
-          def object_property(api, name, property)
-            # A property is never optional, because we specify which are required on the schema itself.
-            actual_type = property.type.is_a?(Apigen::OptionalType) ? property.type.type : property.type
-            [name.to_s, schema(api, actual_type, property.description, property.example)]
+          def model_ref(type)
+            "#/definitions/#{type}"
           end
 
-          def array_schema(api, array_type)
-            {
-              'type' => 'array',
-              'items' => schema(api, array_type.type)
-            }
+          def supports_discriminator?
+            false
           end
         end
       end

data/lib/apigen/formats/openapi.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require_relative './json_base'
 
 module Apigen
   module Formats
@@ -9,6 +10,8 @@ module Apigen
       # OpenAPI 3 generator.
       module V3
         class << self
+          include Apigen::Formats::JsonBase
+
           def generate(api)
             # TODO: Allow overriding any of the hardcoded elements.
             {
@@ -72,13 +75,11 @@ module Apigen
           end
 
           def query_parameter(api, name, property)
-            optional = property.type.is_a?(Apigen::OptionalType)
-            actual_type = optional ? property.type.type : property.type
             parameter = {
               'in' => 'query',
               'name' => name.to_s,
-              'required' => !optional,
-              'schema' => schema(api, actual_type)
+              'required' => property.required?,
+              'schema' => schema(api, property.type)
             }
             parameter['description'] = property.description unless property.description.nil?
             parameter['example'] = property.example unless property.example.nil?
@@ -103,7 +104,7 @@ module Apigen
             response = {}
             response['description'] = output.description unless output.description.nil?
             response['example'] = output.example unless output.example.nil?
-            if output.type != :void
+            if output.type != Apigen::PrimaryType.new(:void)
               response['content'] = {
                 'application/json' => {
                   'schema' => schema(api, output.type)
@@ -113,67 +114,12 @@ module Apigen
             [output.status.to_s, response]
           end
 
-          def definitions(api)
-            hash = {}
-            api.models.each do |key, model|
-              hash[key.to_s] = schema(api, model.type, model.description, model.example)
-            end
-            hash
+          def model_ref(type)
+            "#/components/schemas/#{type}"
           end
 
-          def schema(api, type, description = nil, example = nil)
-            schema = schema_without_description(api, type)
-            schema['description'] = description unless description.nil?
-            schema['example'] = example unless example.nil?
-            schema
-          end
-
-          def schema_without_description(api, type)
-            case type
-            when Apigen::ObjectType
-              object_schema(api, type)
-            when Apigen::ArrayType
-              array_schema(api, type)
-            when Apigen::OptionalType
-              raise 'OptionalType fields are only supported within object types.'
-            when :string
-              {
-                'type' => 'string'
-              }
-            when :int32
-              {
-                'type' => 'integer',
-                'format' => 'int32'
-              }
-            when :bool
-              {
-                'type' => 'boolean'
-              }
-            else
-              return { '$ref' => "#/components/schemas/#{type}" } if api.models.key? type
-              raise "Unsupported type: #{type}."
-            end
-          end
-
-          def object_schema(api, object_type)
-            {
-              'type' => 'object',
-              'properties' => object_type.properties.map { |name, property| object_property(api, name, property) }.to_h,
-              'required' => object_type.properties.reject { |_name, property| property.type.is_a? Apigen::OptionalType }.map { |name, _property| name.to_s }
-            }
-          end
-
-          def object_property(api, name, property)
-            # A property is never optional, because we specify which are required on the schema itself.
-            actual_type = property.type.is_a?(Apigen::OptionalType) ? property.type.type : property.type
-            [name.to_s, schema(api, actual_type, property.description, property.example)]
-          end
-
-          def array_schema(api, array_type)
-            {
-              'type' => 'array',
-              'items' => schema(api, array_type.type)
-            }
+          def supports_discriminator?
+            true
           end
         end
       end

data/lib/apigen/formats/swagger.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require_relative './json_base'
 
 module Apigen
   module Formats
@@ -9,6 +10,8 @@ module Apigen
       # Swagger 2 (aka OpenAPI 2) generator.
       module V2
         class << self
+          include Apigen::Formats::JsonBase
+
           def generate(api)
             # TODO: Allow overriding any of the hardcoded elements.
             {
@@ -71,13 +74,11 @@ module Apigen
           end
 
           def query_parameter(api, name, property)
-            optional = property.type.is_a?(Apigen::OptionalType)
-            actual_type = optional ? property.type.type : property.type
             {
               'in' => 'query',
               'name' => name.to_s,
-              'required' => !optional
-            }.merge(schema(api, actual_type, property.description, property.example))
+              'required' => property.required?
+            }.merge(schema(api, property.type, property.description, property.example))
           end
 
           def input_parameter(api, property)
@@ -96,67 +97,16 @@ module Apigen
             response = {}
             response['description'] = output.description unless output.description.nil?
             response['example'] = output.example unless output.example.nil?
-            response['schema'] = schema(api, output.type) if output.type != :void
+            response['schema'] = schema(api, output.type) if output.type != Apigen::PrimaryType.new(:void)
             [output.status.to_s, response]
           end
 
-          def definitions(api)
-            api.models.map { |key, model| [key.to_s, schema(api, model.type, model.description, model.example)] }.to_h
-          end
-
-          def schema(api, type, description = nil, example = nil)
-            schema = schema_without_description(api, type)
-            schema['description'] = description unless description.nil?
-            schema['example'] = example unless example.nil?
-            schema
-          end
-
-          def schema_without_description(api, type)
-            case type
-            when Apigen::ObjectType
-              object_schema(api, type)
-            when Apigen::ArrayType
-              array_schema(api, type)
-            when Apigen::OptionalType
-              raise 'OptionalType fields are only supported within object types.'
-            when :string
-              {
-                'type' => 'string'
-              }
-            when :int32
-              {
-                'type' => 'integer',
-                'format' => 'int32'
-              }
-            when :bool
-              {
-                'type' => 'boolean'
-              }
-            else
-              return { '$ref' => "#/definitions/#{type}" } if api.models.key? type
-              raise "Unsupported type: #{type}."
-            end
-          end
-
-          def object_schema(api, object_type)
-            {
-              'type' => 'object',
-              'properties' => object_type.properties.map { |name, property| object_property(api, name, property) }.to_h,
-              'required' => object_type.properties.reject { |_name, property| property.type.is_a? Apigen::OptionalType }.map { |name, _property| name.to_s }
-            }
+          def model_ref(type)
+            "#/definitions/#{type}"
           end
 
-          def object_property(api, name, property)
-            # A property is never optional, because we specify which are required on the schema itself.
-            actual_type = property.type.is_a?(Apigen::OptionalType) ? property.type.type : property.type
-            [name.to_s, schema(api, actual_type, property.description, property.example)]
-          end
-
-          def array_schema(api, array_type)
-            {
-              'type' => 'array',
-              'items' => schema(api, array_type.type)
-            }
+          def supports_discriminator?
+            true
           end
         end
       end

data/lib/apigen/migration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Apigen
+  ##
+  # Migration is the base class for API definition migrations.
+  class Migration
+    def initialize(api)
+      @api = api
+    end
+
+    def up
+      raise 'Migration subclasses must implement #up.'
+    end
+
+    def add_endpoint(name, &block)
+      raise 'You must pass a block when calling `add_endpoint`.' unless block_given?
+      @api.endpoint(name, &block)
+    end
+
+    def update_endpoint(name, &block)
+      endpoint = @api.endpoints.find { |e| e.name == name }
+      raise "No such endpoint #{name}." unless endpoint
+      raise 'You must pass a block when calling `update_endpoint`.' unless block_given?
+      endpoint.instance_eval(&block)
+    end
+
+    def remove_endpoint(*names)
+      endpoints = @api.endpoints
+      # This is not algorithmically optimal. We won't do it millions of times though.
+      names.each do |name|
+        raise "No such endpoint :#{name}." unless endpoints.find { |e| e.name == name }
+      end
+      endpoints.reject! { |e| names.include?(e.name) }
+    end
+
+    def add_model(name, &block)
+      @api.model(name, &block)
+    end
+
+    def update_model(name, &block)
+      model = @api.models[name]
+      raise "No such model :#{name}." unless model
+      raise 'You must pass a block when calling `update_model`.' unless block_given?
+      model.instance_eval(&block)
+    end
+
+    def remove_model(*names)
+      models = @api.models
+      names.each do |name|
+        raise "No such model :#{name}." unless models.key? name
+      end
+      names.each { |model_name| models.delete(model_name) }
+    end
+  end
+end