graphiti-openapi 0.1.0

data/app/models/graphiti/open_api/endpoint.rb

@@ -0,0 +1,72 @@
+require "graphiti/open_api"
+require_relative "struct"
+require_relative "action"
+
+module Graphiti::OpenAPI
+  class EndpointData < Struct
+    attribute :actions, Types::Hash.map(Types::Symbol, ActionData)
+
+    def actions
+      Actions.load(self)
+    end
+
+    memoize :actions
+  end
+
+  class Endpoint < EndpointData
+    attribute :schema, Types::Any
+    attribute :path, Types::Coercible::String
+
+    def resource_path
+      File.join(path.to_s, "{id}")
+    end
+
+    def paths
+      {
+        path => {
+          parameters: parameters,
+        }.merge(collection_actions.map(&:operation).inject(&:merge)),
+        resource_path => {
+          parameters: [{'$ref': "#/components/parameters/#{resource.type}_id"}] + parameters,
+        }.merge(resource_actions.map(&:operation).inject(&:merge)),
+      }
+    end
+
+    def parameters
+      [].tap do |parameters|
+        parameters << {'$ref': "#/components/parameters/#{type}_include"} if resource.relationships?
+        parameters << {'$ref': "#/components/parameters/#{type}_sort"}
+        parameters << {'$ref': "#/components/parameters/#{type}_fields"}
+        resource.relationships.values.map do |relationship|
+          relationship.resources.each do |resource|
+            parameters << {'$ref': "#/components/parameters/#{resource.type}_fields"}
+          end
+        end
+      end.uniq
+    end
+
+    def resource
+      resource_actions.first.resource
+    end
+
+    def_instance_delegators :resource, :type
+
+    def resource_actions
+      actions.reject(&:collection?)
+    end
+
+    def collection_actions
+      actions.select(&:collection?)
+    end
+
+    memoize :resource_path, :paths, :parameters, :resource, :resource_actions, :collection_actions
+  end
+
+  class Endpoints < Hash
+    def self.load(schema, data: schema.__attributes__[:endpoints])
+      data.each_with_object({}) do |(path, data), result|
+        result[path] = Endpoint.new(data.to_hash.merge(schema: schema, path: path))
+      end
+    end
+  end
+end

data/app/models/graphiti/open_api/functions.rb

@@ -0,0 +1,16 @@
+require "graphiti/open_api"
+require "transproc"
+require "transproc/recursion"
+
+module Graphiti::OpenAPI
+  module Functions
+    extend Transproc::Registry
+
+    import Transproc::HashTransformations
+    import Transproc::Recursion
+
+    def self.deep_reject_keys(hash, keys)
+      t(:hash_recursion, t(:reject_keys, keys))[hash]
+    end
+  end
+end

data/app/models/graphiti/open_api/generator.rb

@@ -0,0 +1,174 @@
+require "graphiti/open_api"
+require "forwardable"
+require "dry/core/memoizable"
+require_relative "functions"
+require_relative "schema"
+
+module Graphiti::OpenAPI
+  class Generator
+    extend Forwardable
+    include Dry::Core::Memoizable
+
+    def initialize(
+                   root: Rails.root,
+                   schema: root.join("public#{ApplicationResource.endpoint_namespace}").join("schema.json"),
+                   jsonapi: root.join("public/schemas/jsonapi.json"),
+                   template: root.join("config/openapi.yml"))
+      @root = Pathname(root)
+      @schema_path = schema
+      @jsonapi_path = jsonapi
+      @template_path = template
+    end
+
+    # @!attribute [r] root
+    #   @return [Pathname]
+    # @!attribute [r] schema
+    #   @return [{String => Source}]
+    attr_reader :root
+
+    def schema
+      Schema.new(schema_source.data)
+    end
+
+    def_instance_delegators :schema,
+                            :endpoints, :resources, :types,
+                            :resource
+
+    def schema_source(path = @schema_path)
+      Source.load(path)
+    end
+
+    def template_source(path = @template_path)
+      Source.load(path, parse: YAML.method(:safe_load))
+    end
+
+    def paths
+      @paths ||=
+        endpoints.values.map(&:paths).inject(&:merge)
+    end
+
+    def to_openapi(format: :json)
+      template = template_source.data
+      data = {
+        openapi: "3.0.1",
+        servers: [{url: Rails.application.routes.default_url_options[:host], description: "#{Rails.env} server"}],
+        tags: tags,
+        paths: paths,
+        components: {
+          schemas: schemas,
+          parameters: parameters,
+          requestBodies: request_bodies,
+          responses: responses,
+          links: links,
+        },
+      }
+      specification = Functions[:deep_merge][template, data]
+      case format
+      when :json
+        specification
+      when :yaml
+        json = specification.to_json
+        JSON.parse(json).to_yaml
+      else
+        raise ArgumentError, "Unknown format: `#{format.inspect}`"
+      end
+    end
+
+    private
+
+    def tags
+      resources.values.map do |resource|
+        {
+          name: resource.type,
+          description: "#{resource.human} operations",
+        }
+      end
+    end
+
+    def request_bodies
+      resources.values.each_with_object({}) do |resource, result|
+        result[resource.type] = {
+          required: true,
+          content: {
+            "application/vnd.api+json" => {schema: {"$ref": "#/components/schemas/#{resource.type}_request"}},
+          # "application/xml" => {schema: {"$ref": "#/components/schemas/#{resource.type}_request"}},
+          },
+        }
+      end
+    end
+
+    def responses
+      resources.values.map(&:to_responses).inject(&:merge).compact
+    end
+
+    def links
+      resources.values.map(&:to_links).inject(&:merge).compact
+    end
+
+    def schemas
+      {types: {type: :string, enum: resources.values.map(&:type)}}
+        .merge(resources.values.map(&:to_schema).inject(&:merge))
+        .merge(jsonapi_definitions)
+    end
+
+    def parameters
+      resources.values.map(&:to_parameters).inject(&:merge)
+    end
+
+    REWRITE_JSONAPI_SCHEMA = -> (text) do
+      text
+        .gsub("/definitions/", "/components/schemas/jsonapi_")
+        .gsub(%r'"type": "null"', '"nullable": true')
+      # .gsub(%r',\s*{\s*"type": "null"\s*}\s*', ', "nullable": true')
+    end
+
+    PROCESS_JSONAPI_SCHEMA = Source::DEFAULT_PROCESS >>
+                             # Reject unsupported schema properties
+                             Functions[:deep_reject_keys,
+                                       %i[$schema additionalItems const contains dependencies id $id patternProperties propertyNames]
+                             ]
+
+    PREFIX_JSONAPI_DEFINITIONS = Functions[:map_keys, -> (key) { "jsonapi_#{key}" }]
+
+    def jsonapi_source(path = @jsonapi_path)
+      Source.load(path, rewrite: REWRITE_JSONAPI_SCHEMA, process: PROCESS_JSONAPI_SCHEMA)
+    end
+
+    def jsonapi_definitions
+      defs = jsonapi_source.data[:definitions]
+      defs[:jsonapi][:properties][:version][:example] = "1.0"
+
+      # Provide meaningful linkages in examples
+      variants = defs[:relationshipToOne].delete(:anyOf)
+      variants = variants.keep_if { |item| item[:$ref] !~ /empty/ }
+      defs[:relationshipToOne][:oneOf] = variants + [nullable: true]
+
+      # Provide real types and id examples
+      %i[resource linkage].each do |schema|
+        defs[schema][:properties][:id] = {type: :string, example: rand(100).to_s}
+        defs[schema][:properties][:type] = {'$ref': "#/components/schemas/types"}
+      end
+
+      # Use real resources in examples
+      defs[:resource] = {
+        oneOf: resources.values.map { |resource| {'$ref': "#/components/schemas/#{resource.type}_resource"} },
+      }
+
+      # Fix OpenAPI and JSON Schema differences
+      defs[:relationshipLinks][:properties][:self].delete(:description)
+
+      # Hide meta & links
+      %i[meta links relationshipLinks].each do |schema|
+        original = defs.delete(schema)
+        defs[schema] = {oneOf: [{nullable: true}, original]}
+      end
+
+      # Remove unused elements
+      %i[attributes empty].each { |schema| defs.delete(schema) }
+
+      PREFIX_JSONAPI_DEFINITIONS[defs]
+    end
+
+    memoize :jsonapi_source, :jsonapi_definitions, :schema_source, :schema, :template_source
+  end
+end

data/app/models/graphiti/open_api/parameters.rb

@@ -0,0 +1,30 @@
+require "graphiti/open_api"
+
+module Graphiti::OpenAPI
+  module Parameters
+    def parameter(name, desc: nil, **options)
+      options.merge(name: name).tap do |parameter|
+        parameter[:description] = desc if desc
+      end
+    end
+
+    def query_parameter(name, **options)
+      parameter(name, in: :query, **options)
+    end
+
+    def path_parameter(name, required: true, **options)
+      parameter(name, in: :path, required: required, **options)
+    end
+
+    def array_enum(enum, type: :string, uniq: true)
+      {
+        type: :array,
+        items: {
+          type: type,
+          enum: enum,
+          uniqueItems: uniq,
+        },
+      }
+    end
+  end
+end

data/app/models/graphiti/open_api/relationship.rb

@@ -0,0 +1,65 @@
+require "graphiti/open_api"
+require_relative "struct"
+
+module Graphiti::OpenAPI
+  class RelationshipData < Struct
+    attribute :type, Types::String
+    attribute :description, Types::String.optional
+    attribute? :resource, Types::String.optional
+    attribute? :resources, Types.Array(Types::String).default([])
+  end
+
+  class Relationship < RelationshipData
+    attribute :origin, Types::Any
+    attribute :name, Types::Symbol
+
+    def_instance_delegator :origin, :schema
+
+    def resource
+      return unless __attributes__[:resource]
+      schema.resources[__attributes__[:resource]]
+    end
+
+    def resources
+      return [resource] if __attributes__[:resources].empty?
+      __attributes__[:resources].map { |resource| schema.resources[resource] }
+    end
+
+    def to_schema
+      {
+        name => {
+          type: :object,
+          properties: {
+            links: {"$ref": "#/components/schemas/jsonapi_relationshipLinks"},
+            data: {'$ref': "#/components/schemas/#{jsonapi_relationship}"},
+            meta: {"$ref": "#/components/schemas/jsonapi_meta"},
+          },
+        },
+
+      }
+    end
+
+    def jsonapi_relationship
+      case type
+      when /belongs_to/, "has_one"
+        "jsonapi_relationshipToOne"
+      else
+        "jsonapi_relationshipToMany"
+      end
+    end
+
+    memoize :resource, :resources
+  end
+
+  class Relationships < Hash
+    def self.load(resource, data = resource.__attributes__[:relationships])
+      data.each_with_object(new) do |(name, data), result|
+        result[name] = Relationship.new(data.to_hash.merge(name: name, origin: resource))
+      end
+    end
+
+    def resources
+      values.map(&:resources).flatten.uniq.compact
+    end
+  end
+end

data/app/models/graphiti/open_api/resource.rb

@@ -0,0 +1,322 @@
+require "graphiti/open_api"
+require "active_model"
+require_relative "struct"
+require_relative "attribute"
+require_relative "relationship"
+
+module Graphiti::OpenAPI
+  class ResourceData < Struct
+    attribute :name, Types::String
+    attribute :type, Types::String
+    attribute :description, Types::String.optional
+    attribute :attributes, Types::Hash.map(Types::Symbol, AttributeData)
+    attribute :extra_attributes, Types::Hash.map(Types::Symbol, AttributeData)
+    attribute :sorts, Types::Hash.map(Types::Symbol, Types::Hash)
+    attribute :filters, Types::Hash.map(Types::Symbol, Types::Hash)
+    attribute :relationships, Types::Hash.map(Types::Symbol, RelationshipData)
+
+    def relationships
+      Relationships.load(self)
+    end
+
+    def relationships?
+      relationships.any?
+    end
+
+    memoize :relationships
+  end
+
+  class Resource < ResourceData
+    include Parameters
+
+    attribute :schema, Types::Any
+
+    def model_name
+      ActiveModel::Name.new(self.class, nil, name.gsub(/Resource/, ""))
+    end
+
+    def_instance_delegators :model_name, :human, :singular, :plural
+
+    def plural_human(**options)
+      human(**options).pluralize
+    end
+
+    def attributes
+      Attributes.load(self)
+    end
+
+    def extra_attributes
+      Attributes.load(self, __attributes__[:extra_attributes])
+    end
+
+    def all_attributes
+      attributes.merge(extra_attributes)
+    end
+
+    def resource_attributes
+      all_attributes.except(:id).values
+    end
+
+    def readable_attributes
+      all_attributes.values.select(&:readable)
+    end
+
+    def sortable_attributes
+      sortable_attribute_names = sorts.keys
+      all_attributes.values.select { |attribute| sortable_attribute_names.include?(attribute.name) }
+    end
+
+    def writable_attributes
+      all_attributes.values.select(&:writable)
+    end
+
+    def query_parameters
+      [].tap do |result|
+        result << query_include_parameter
+        result << query_fields_parameter
+      end
+    end
+
+    def query_fields_parameter
+      schema = {
+        description: "#{human} readable attributes list",
+        type: :array,
+        items: {'$ref': "#/components/schemas/#{type}_readable_attribute"},
+        uniqueItems: true,
+      }
+
+      query_parameter("fields[#{type}]",
+                      desc: "[Include only specified fields of #{human} in response](https://jsonapi.org/format/#fetching-sparse-fieldsets)",
+                      schema: schema,
+                      explode: false)
+    end
+
+    def query_include_parameter
+      return unless relationships?
+
+      query_parameter(:include, desc: "[Include related resources](https://jsonapi.org/format/#fetching-includes)", schema: {'$ref': "#/components/schemas/#{type}_related"}, explode: false)
+    end
+
+    def query_sort_parameter(relationships: false)
+      return unless sorts.any?
+      orderings = sorts.keys.map { |id| %W[#{id} -#{id}] }.flatten
+      if relationships
+        relationships.each do |name, relationship|
+          relationship.resources.each do |resource|
+            orderings += resource.sorts.keys.map { |id| %W[#{name}.#{id} -#{name}.#{id}] }.flatten
+          end
+        end
+      end
+      query_parameter(:sort,
+                      desc: "[Sort #{model_name.plural} according to one or more criteria](https://jsonapi.org/format/#fetching-sorting)\n\n" \
+                            "You should not include both ascending `id` and descending `-id` fields the same time\n\n",
+                      schema: {"$ref" => "#/components/schemas/#{type}_sortable_attributes_list"}, explode: false)
+    end
+
+    def to_parameters
+      {
+        "#{type}_id": path_parameter(:id, schema: {type: :string}, desc: "ID of the resource"),
+        "#{type}_include": query_include_parameter,
+        "#{type}_fields": query_fields_parameter,
+        "#{type}_sort": query_sort_parameter,
+      }.keep_if { |name, value| value }
+    end
+
+    def to_schema
+      attributes_schema
+        .merge(relationships_schema)
+        .merge(resource_schema)
+        .merge(response_schema)
+        .merge(request_schema)
+        .merge(attribute_schemas)
+    end
+
+    def attributes_schema
+      {
+        type => {
+          type: :object,
+          description: "#{human} attributes",
+          properties: resource_attributes.map(&:to_property).inject(&:merge),
+          additionalProperties: false,
+        },
+      }
+    end
+
+    def relationships_schema
+      schema_name = "#{type}_relationships"
+      return {schema_name => {'$ref': "#/components/schemas/jsonapi_relationships"}} unless relationships?
+      {
+        schema_name => {
+          type: :object,
+          properties: relationships.values.map(&:to_schema).inject(&:merge),
+          additionalProperties: false,
+        },
+      }
+    end
+
+    def resource_schema
+      {
+        "#{type}_resource" => {
+          type: :object,
+          properties: {
+            id: {type: :string, example: rand(100).to_s},
+            type: {type: :string, enum: [type]},
+            attributes: {'$ref': "#/components/schemas/#{type}"},
+            relationships: {'$ref': "#/components/schemas/#{type}_relationships"},
+            links: {'$ref': "#/components/schemas/jsonapi_links"},
+          },
+          additionalProperties: false,
+        },
+      }
+    end
+
+    def response_schema
+      {
+        "#{type}_single" => {
+          type: :object,
+          allOf: [
+            {'$ref': "#/components/schemas/jsonapi_success"},
+            {
+              type: :object,
+              properties: {
+                data: {'$ref': "#/components/schemas/#{type}_resource"},
+              },
+            },
+          ],
+        },
+        "#{type}_collection" => {
+          type: :object,
+          allOf: [
+            {'$ref': "#/components/schemas/jsonapi_success"},
+            {
+              type: :object,
+              properties: {
+                data: {
+                  type: :array,
+                  items: {"$ref" => "#/components/schemas/#{type}_resource"},
+                },
+              },
+            },
+          ],
+        },
+      }
+    end
+
+    def request_schema
+      {
+        "#{type}_request" => {
+          type: :object,
+          properties: {
+            data: {'$ref': "#/components/schemas/#{type}_resource"},
+          },
+        # xml: {name: :data},
+        },
+      }
+    end
+
+    def attribute_schemas
+      types = {
+        "#{type}_readable_attribute" => {
+          description: "#{human} readable attributes",
+          type: :string,
+          enum: readable_attributes.map(&:name),
+        },
+        "#{type}_sortable_attributes_list" => {
+          description: "#{human} sortable attributes",
+          type: :array,
+          items: {
+            type: :string,
+            enum: sortable_attribute_names.map { |name| %W[#{name} -#{name}] }.flatten,
+          },
+          uniqueItems: true,
+        },
+        "#{type}_related" => {
+          description: "#{human} relationships available for inclusion",
+          type: :array,
+          items: {type: :string},
+          uniqueItems: true,
+        },
+
+      }
+      if relationship_names.any?
+        types["#{type}_related"][:items][:enum] = relationship_names
+      else
+        types["#{type}_related"][:nullable] = true
+      end
+      types
+    end
+
+    def to_responses
+      {
+        "#{type}_200" => {
+          description: "OK: #{human} resource",
+          content: {
+            "application/vnd.api+json" => {schema: {"$ref": "#/components/schemas/#{type}_single"}},
+          # "application/xml" => {schema: {"$ref": "#/components/schemas/#{type}_single"}},
+          },
+          links: link_refs,
+        },
+        "#{type}_200_collection" => {
+          description: "OK: #{plural_human} collection",
+          content: {
+            "application/vnd.api+json" => {schema: {"$ref": "#/components/schemas/#{type}_collection"}},
+          # "application/xml" => {schema: {"$ref": "#/components/schemas/#{type}_collection"}},
+          },
+        },
+        "#{type}_201" => {
+          description: "Created",
+          content: {
+            "application/vnd.api+json" => {schema: {"$ref": "#/components/schemas/#{type}_single"}},
+          # "application/xml" => {schema: {"$ref": "#/components/schemas/#{type}_single"}},
+          },
+          links: link_refs,
+        },
+      }
+    end
+
+    def to_links
+      %i[get update delete].inject({}) do |result, method|
+        operation_id = "#{method}_#{model_name.singular}".camelize(:lower)
+        result.merge(
+          "#{operation_id}Id": {
+            operationId: operation_id,
+            parameters: {id: "$response.body#/data/id"},
+          },
+        )
+      end
+    end
+
+    memoize :model_name, :attributes, :query_parameters, :to_schema, :to_responses, :to_links
+
+    private
+
+    def link_refs
+      to_links.keys.inject({}) { |result, link| result.merge(link => {'$ref': "#/components/links/#{link}"}) }
+    end
+
+    def relationship_names
+      relationships.keys
+    end
+
+    def sortable_attribute_names
+      sortable_attributes.map(&:name)
+    end
+  end
+
+  class Resources < Hash
+    # @param [<ResourceData>]
+    def self.load(schema, data = schema.__attributes__[:resources])
+      data.each_with_object(new) do |resource, result|
+        result[resource.name] = Resource.new(resource.to_hash.merge(schema: schema))
+      end
+    end
+
+    def by_model(model)
+      fetch("#{model}Resource")
+    end
+
+    def by_type(type)
+      values.detect { |resource| resource.type = type }
+    end
+  end
+end