open_api_annotator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c25f0d206c6a39ed21f7dd1a15fb886aaad9e6ed05db73aeda5ffa7e852a1ed
+  data.tar.gz: ce7c5a930ec200636792afee7e4545ac13e8ebcc703281dd0da9da431d1857d6
+SHA512:
+  metadata.gz: 5a7ac62a5ce7fddc89b62b8694f5e0c364a18d963b162f6b7479229d7e5ad1571fda1d64690eef4f1cd833c6bd661e4956788469e6357cf6b2769a3844b26610
+  data.tar.gz: 5ba222eb03b1a1496ef8ce300cf5eaef0b179ee4e5b365348351c71a4eb78da607f8d3b2a1093013e3ad925e09b751b82f7db4b72b2ae62fe2983535aba06472

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+Gemfile.lock
+
+# rspec failure tracking
+.rspec_status
+coverage

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.5.1

data/.travis.yml

@@ -0,0 +1,15 @@
+env:
+  global:
+    - CC_TEST_REPORTER_ID=921d046db793707b7d0c0d1305970a137fdf98fbc6ceeb6c355c44757040244f
+sudo: false
+language: ruby
+rvm:
+  - 2.4.4
+  - 2.5.1
+before_install: gem install bundler -v 1.16.1
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 0.1.0
+First release
+
+* Enable to YAML spec file to annotate controllers and serializers

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at ngtknt@me.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in open_api_annotator.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Kent Nagata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,91 @@
+# OpenApiAnnotator [![Build Status](https://travis-ci.org/ngtk/open_api_annotator.svg?branch=master)](https://travis-ci.org/ngtk/open_api_annotator) [![Maintainability](https://api.codeclimate.com/v1/badges/8be7a273496459c62190/maintainability)](https://codeclimate.com/github/ngtk/open_api_annotator/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/8be7a273496459c62190/test_coverage)](https://codeclimate.com/github/ngtk/open_api_annotator/test_coverage)
+
+OpenApiAnnotator realizes to generate OpenApi spec by annotating to controllers and serializers.
+If you use ActiveModelSerializer, this is the best to generate OpenAPI spec.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'open_api_annotator'
+```
+
+## Usage
+
+Annotating controllers and serializers, you can generate OpenAPI spec file from these.
+Things you have to do are three below:
+
+1. Configure API meta information
+1. Annotate controllers
+1. Annotate serializers
+
+### 1. Configure API meta information
+You have to set API meta information like:
+
+```rb
+# config/initializers/open_api_annotator.rb
+OpenApiAnnotator.configure do |config|
+  config.info = OpenApi::Info.new(title: "Book API", version: "1")
+  config.destination_path = Rails.root.join("api_spec.yml")
+  config.path_regexp = /\Aapi\/v1\// # If you want to restrict a path to create
+end
+```
+
+
+### 2. Annotate controller
+To define an entity of an endpoint, call the method `endpoint` in the previous line of an action method. It takes entity expression as the first arg. Entity expression is a model class or an array that contains only one model class.
+
+```rb
+class Api::V1::BooksController
+  endpoint [Book] # 👈It means an array of Book
+  def index
+    books = Book.limit(10)
+    render json: books
+  end
+
+  endpoint Book # 👈Just a Book
+  def show
+    book = Book.find(params[:id])
+    render json: book
+  end
+
+  endpoint Book # 👈Just a Book
+  def update
+     book = Book.find(params[:id])
+     book.update!(book_params)
+     render json: book
+  end
+end
+```
+
+### 3. Annotate serializer
+To define an schema in components, set `type`, `format`, `nullable` as each field option.
+
+```rb
+class BookSerializer < ApplicationSerializer
+  attribute :title, type: :string, nullable: false
+  attribute :published_at, type: :string, format: :"date-time", nullable: true
+
+  has_many :authors, type: [Author], nullable: false
+  has_one :cover_image, type: CoverImage, nullable: true
+  belongs_to :publisher, type: Publisher, nullable: false
+end
+```
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ngtk/open_api_annotator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the OpenApiAnnotator project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ngtk/open_api_annotator/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "bump/tasks"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "open_api_annotator"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/open_api_annotator.rb

@@ -0,0 +1,41 @@
+require "active_support"
+require "active_support/concern"
+require "active_support/core_ext/class/subclasses"
+
+require 'rails'
+
+require 'open_api'
+
+require 'open_api_annotator/field'
+require 'open_api_annotator/attribute'
+require 'open_api_annotator/association'
+require 'open_api_annotator/version'
+require 'open_api_annotator/errors'
+require 'open_api_annotator/controller_annotatable'
+require 'open_api_annotator/serializer_annotatable'
+require 'open_api_annotator/type_validator'
+require 'open_api_annotator/format_validator'
+require 'open_api_annotator/nullable_validator'
+require 'open_api_annotator/paths_builder'
+require 'open_api_annotator/components_builder'
+require 'open_api_annotator/spec_builder'
+
+require 'open_api_annotator/config'
+require 'open_api_annotator/configurable'
+
+module OpenApiAnnotator
+  include Configurable
+
+  def self.create_spec_yaml
+    info = config.info
+    spec = SpecBuilder.new.build(info: info)
+    yaml = OpenApi::Serializers::YamlSerializer.new.serialize(spec)
+    File.write(config.destination_path, yaml)
+  end
+
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load "tasks/api_spec.rake"
+    end
+  end
+end

data/lib/open_api_annotator/association.rb

@@ -0,0 +1,3 @@
+module OpenApiAnnotator
+  class Association < Field; end
+end

data/lib/open_api_annotator/attribute.rb

@@ -0,0 +1,10 @@
+module OpenApiAnnotator
+  class Attribute < Field
+    attr_accessor :format
+
+    def initialize(name, type, format, nullable)
+      super(name, type, nullable)
+      self.format = format
+    end
+  end
+end

data/lib/open_api_annotator/components_builder.rb

@@ -0,0 +1,79 @@
+module OpenApiAnnotator
+  class ComponentsBuilder
+    def build
+      components = OpenApi::Components.new(schemas: {})
+
+      serializers = fetch_all_serializers
+      serializers.sort_by!(&:open_api_resource_name)
+      serializers.each do |serializer|
+        schema = build_schema(serializer)
+        next unless schema
+        components.schemas[serializer.open_api_resource_name] = schema
+        puts "Schema component '#{serializer.open_api_resource_name}' has been created."
+      end
+      components
+    end
+
+    private
+
+    def build_schema(serializer)
+      schema = OpenApi::Schema.new(type: "object", properties: {})
+      schema.properties.merge!(build_attribute_properties(serializer))
+      schema.properties.merge!(build_has_many_association_properties(serializer))
+      schema.properties.merge!(build_has_one_and_belongs_to_association_properties(serializer))
+      schema
+    end
+
+    def build_attribute_properties(serializer)
+      properties = {}
+      serializer.open_api_attributes.each do |attribute|
+        next unless attribute.valid?
+        properties[attribute.name.to_sym] = OpenApi::Schema.new(
+          type: attribute.type,
+          format: attribute.format,
+          nullable: attribute.nullable,
+        )
+      end
+      properties
+    end
+
+    def build_has_many_association_properties(serializer)
+      properties = {}
+      serializer.open_api_has_many_associations.each do |association|
+        next unless association.valid?
+        content = association.type.first
+        return unless content
+        content_name = content.try(:name) || content.to_s
+        properties[association.name.to_sym] = OpenApi::Schema.new(
+          type: "array",
+          items: OpenApi::Reference.new(ref: "#/components/schemas/#{content_name}"),
+          nullable: association.nullable,
+        )
+      end
+      properties
+    end
+
+    def build_has_one_and_belongs_to_association_properties(serializer)
+      properties = {}
+      associations = serializer.open_api_has_one_associations + serializer.open_api_belongs_to_associations
+      associations.each do |association|
+        next unless association.valid?
+        content_name = association.type.try(:name) || association.type.to_s
+        properties[association.name.to_sym] = OpenApi::Reference.new(ref: "#/components/schemas/#{content_name}")
+      end
+      properties
+    end
+
+    def fetch_all_serializers
+      require_all_serializers!
+
+      OpenApiAnnotator.config.application_serializer_class.descendants
+    end
+
+    def require_all_serializers!
+      all_serializer_features = Dir["#{Rails.root}/app/serializers/**/*_serializer.rb"]
+      unloaded_features = all_serializer_features - $LOADED_FEATURES
+      unloaded_features.each { |f| require f }
+    end
+  end
+end

data/lib/open_api_annotator/config.rb

@@ -0,0 +1,100 @@
+module OpenApiAnnotator
+  class Config < Struct.new(
+    :info,
+    :destination_path,
+    :path_regexp,
+    :application_controller_class_name,
+    :application_serializer_class_name,
+  )
+    def application_serializer_class
+      if application_serializer_class_name
+        application_serializer_class_name.constantize
+      else
+        unless defined?(ApplicationSerializer)
+          raise <<~EOL
+            Expected to define ApplicationSerializer or set custom class like:
+
+            ```
+            OpenApiAnnotator.configure do |config|
+              config.application_serializer_class = BaseSerializer
+            end
+            ```
+          EOL
+        end
+        ApplicationSerializer
+      end
+    end
+
+    def application_controller_class
+      if application_controller_class_name
+        application_controller_class_name.constantize
+      else
+        unless defined?(ApplicationController)
+          raise <<~EOL
+            Expected to define ApplicationController or set custom class like:
+
+            ```
+            OpenApiAnnotator.configure do |config|
+              config.application_controller_class = BaseSerializer
+            end
+            ```
+          EOL
+        end
+        ApplicationController
+      end
+    end
+
+    def validate!
+      validate_info!
+      validate_destination_path!
+      validate_path_regexp!
+      validate_application_controller_class_name!
+      validate_application_serializer_class_name!
+    end
+
+    def validate_info!
+      unless info
+        raise InvalidError, <<~EOL
+          You have to set `OpenApi::Info` to `config.info` like:
+
+          ```
+          OpenApiAnnotator.configure do |config|
+            config.info = OpenApi::Info.new(title: "Book API", version: "1")
+          end
+          ```
+
+          You can see the detail of `OpenApi::Info` in
+          https://www.rubydoc.info/gems/open_api/OpenApi/Info
+        EOL
+      end
+    end
+
+    def validate_destination_path!
+      unless destination_path
+        raise InvalidError, <<~EOL
+          You have to set `config.destination_path` like:
+
+          ```
+          OpenApiAnnotator.configure do |config|
+            config.destination_path = Rails.root.join("api_spec.yml")
+          end
+          ```
+        EOL
+      end
+    end
+
+    def validate_path_regexp!
+      # Do nothing
+    end
+
+    def validate_application_serializer_class_name!
+      # Do nothing
+    end
+
+    def validate_application_controller_class_name!
+      # Do nothing
+    end
+
+    class InvalidError < StandardError; end
+  end
+end

data/lib/open_api_annotator/configurable.rb

@@ -0,0 +1,16 @@
+module OpenApiAnnotator
+  module Configurable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def configure(&block)
+        block.call(config)
+        config.validate!
+      end
+
+      def config
+        @config ||= Config.new
+      end
+    end
+  end
+end

data/lib/open_api_annotator/controller_annotatable.rb

@@ -0,0 +1,45 @@
+module OpenApiAnnotator
+  module ControllerAnnotatable
+    def type_hash
+      @type_hash ||= {}
+    end
+
+    def validate_open_api_type!(type)
+      @open_api_type_validator ||= TypeValidator.new
+      @open_api_type_validator.validate!(type)
+    end
+
+    def endpoint(type)
+      validate_open_api_type!(type)
+      @last_type = type
+
+    rescue ValidationError => e
+      raise TypeError, <<~EOL
+      #{e.message}
+
+      Examples:
+        - `[Project]`: means collection of Project
+        - `Project`: means single resouce Project
+
+      In your controller:
+
+        endpoint [Project]
+        def index
+          # ... some code
+        end
+      EOL
+    end
+
+    def method_added(name)
+      super
+      return unless @last_type
+
+      type = @last_type
+      @last_type = nil
+
+      return if private_method_defined?(name)
+
+      type_hash[name] = type
+    end
+  end
+end

data/lib/open_api_annotator/errors.rb

@@ -0,0 +1,3 @@
+module OpenApiAnnotator
+  class ValidationError < StandardError; end
+end

data/lib/open_api_annotator/field.rb

@@ -0,0 +1,11 @@
+module OpenApiAnnotator
+  class Field < Struct.new(:name, :type, :nullable)
+    def valid?
+      return false if name.nil?
+      return false if type.nil?
+      return false if nullable.nil?
+
+      true
+    end
+  end
+end

data/lib/open_api_annotator/format_validator.rb

@@ -0,0 +1,7 @@
+module OpenApiAnnotator
+  class FormatValidator
+    def validate!(format)
+      true # format is a open value and nillable
+    end
+  end
+end

data/lib/open_api_annotator/nullable_validator.rb

@@ -0,0 +1,9 @@
+module OpenApiAnnotator
+  class NullableValidator
+    def validate!(nullable)
+      if nullable.nil?
+        raise ValidationError, "nullable should not be nil."
+      end
+    end
+  end
+end

data/lib/open_api_annotator/paths_builder.rb

@@ -0,0 +1,119 @@
+module OpenApiAnnotator
+  class PathsBuilder
+    def build
+      paths = OpenApi::Paths.new
+      routes = RoutesFinder.new.find_all
+      if OpenApiAnnotator.config.path_regexp
+        routes.select! { |route| route.path.match(OpenApiAnnotator.config.path_regexp) }
+      end
+      routes.group_by(&:path).each do |path_name, routes|
+        paths[path_name] = build_path_item(routes)
+        puts "Path '#{path_name}' has been created."
+      end
+
+      paths
+    end
+
+    private
+
+    def build_path_item(routes)
+      path_item = OpenApi::PathItem.new
+      routes.each do |route|
+        media_type = resolve_media_type(route.controller_name, route.action_name)
+        description = build_description(route.controller_name, route.action_name)
+        next unless media_type
+        response = OpenApi::Response.new(
+          description: description,
+          content: {
+            "application/json" => media_type,
+          }
+        )
+        operation = OpenApi::Operation.new(responses: OpenApi::Responses.new)
+        operation.responses["200"] = response
+        path_item.operations[route.http_verb.underscore] = operation
+      end
+      path_item
+    end
+
+    def build_description(controller_name, action_name)
+      type = resolve_type(controller_name, action_name)
+      return unless type
+
+      case type
+      when Array
+        "Returns array of #{type.first.name}"
+      when Class
+        "Returns #{type.name}"
+      else
+        raise "not supported class #{type.class}"
+      end
+    end
+
+    def resolve_media_type(controller_name, action_name)
+      type = resolve_type(controller_name, action_name)
+      return unless type
+
+      case type
+      when Array
+        content_class = type.first
+        reference = OpenApi::Reference.new(ref: "#/components/schemas/#{content_class.name}")
+        schema = OpenApi::Schema.new(type: "array", items: reference)
+        OpenApi::MediaType.new(schema: schema)
+      when Class
+        reference = OpenApi::Reference.new(ref: "#/components/schemas/#{type.name}")
+        OpenApi::MediaType.new(schema: reference)
+      else
+        raise "not supported class #{type.class}"
+      end
+    end
+
+    def resolve_type(controller_name, action_name)
+      controller_class_name = "#{controller_name}_controller".classify
+      begin
+        controller_class = controller_class_name.constantize
+      rescue NameError => e
+        return
+      end
+      return unless controller_class < OpenApiAnnotator.config.application_controller_class
+
+      controller_class.type_hash[action_name.to_sym]
+    end
+  end
+
+  Route = Struct.new(:http_verb, :path, :controller_name, :action_name) do
+    def initialize(http_verb:, path:, controller_name:, action_name:)
+      self.http_verb = http_verb
+      self.path = path
+      self.controller_name = controller_name
+      self.action_name = action_name
+    end
+  end
+
+  class RoutesFinder
+    def find_all
+      @routes ||= Rails.application.routes.routes.routes.map do |route|
+        path = PathResolver.new.resolve(route.path.ast)
+        controller = route.requirements[:controller]
+        action = route.requirements[:action]
+        Route.new(http_verb: route.verb, path: path, controller_name: controller, action_name: action)
+      end
+    end
+  end
+
+  class PathResolver
+    def resolve(ast)
+      res = ""
+      if ast.type == :CAT
+        left = ast.left
+        res +=
+          if left.type == :SYMBOL
+            "{#{left.name}}"
+          else
+            left.to_s
+          end
+        res += resolve(ast.right)
+      end
+      res
+    end
+  end
+end

data/lib/open_api_annotator/serializer_annotatable.rb

@@ -0,0 +1,100 @@
+module OpenApiAnnotator
+  module SerializerAnnotatable
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def skip_open_api_validation!
+        @open_api_validation_skipped = true
+      end
+
+      def attribute(attr, options = {}, &block)
+        validate_open_api_options(attr, options)
+        super(attr, options, &block)
+      end
+
+      def has_many(name, options = {}, &block)
+        validate_open_api_options(name, options)
+        super(name, options, &block)
+      end
+
+      def has_one(name, options = {}, &block)
+        validate_open_api_options(name, options)
+        super(name, options, &block)
+      end
+
+      def belongs_to(name, options = {}, &block)
+        validate_open_api_options(name, options)
+        super(name, options, &block)
+      end
+
+      def validate_open_api_options(field, options)
+        return if @open_api_validation_skipped
+
+        validate_open_api_type!(options[:type])
+        validate_open_api_format!(options[:format])
+        validate_open_api_nullable!(options[:nullable])
+      rescue ValidationError => e
+        Rails.logger.warn(e.message)
+      end
+
+      def validate_open_api_type!(type)
+        @open_api_type_validator ||= TypeValidator.new
+        @open_api_type_validator.validate!(type)
+      end
+
+      def validate_open_api_nullable!(type)
+        @open_api_nullable_validator ||= NullableValidator.new
+        @open_api_nullable_validator.validate!(type)
+      end
+
+      def validate_open_api_format!(format)
+        @open_api_format_validator ||= FormatValidator.new
+        @open_api_format_validator.validate!(format)
+      end
+
+      def open_api_has_many_associations
+        _reflections.values.select { |reflection|
+          reflection.is_a?(ActiveModel::Serializer::HasManyReflection)
+        }.map do |reflection|
+          serializer_class = reflection.options[:serializer]
+          type = serializer_class ? [serializer_class.open_api_resource_name] : reflection.options[:type]
+          Association.new(reflection.name.to_sym, type, reflection.options[:nullable])
+        end
+      end
+
+      def open_api_has_one_associations
+        _reflections.values.select { |reflection|
+          reflection.is_a?(ActiveModel::Serializer::HasOneReflection)
+        }.map do |reflection|
+          serializer_class = reflection.options[:serializer]
+          type = serializer_class ? [serializer_class.open_api_resource_name] : reflection.options[:type]
+          Association.new(reflection.name.to_sym, type, reflection.options[:nullable])
+        end
+      end
+
+      def open_api_belongs_to_associations
+        _reflections.values.select { |reflection|
+          reflection.is_a?(ActiveModel::Serializer::BelongsToReflection)
+        }.map do |reflection|
+          serializer_class = reflection.options[:serializer]
+          type = serializer_class ? [serializer_class.open_api_resource_name] : reflection.options[:type]
+          Association.new(reflection.name.to_sym, type, reflection.options[:nullable])
+        end
+      end
+
+      def open_api_attributes
+        _attributes_data.values.reject { |attribute|
+          attribute.name.to_s.start_with?("_")
+        }.map { |attribute|
+          serializer_class = attribute.options[:serializer]
+          type = serializer_class ? [serializer_class.open_api_resource_name] : attribute.options[:type]
+          Attribute.new(attribute.name.to_sym, type, attribute.options[:format], attribute.options[:nullable])
+        }
+      end
+
+      def open_api_resource_name
+        name.remove(/Serializer\z/)
+      end
+    end
+  end
+end

data/lib/open_api_annotator/spec_builder.rb

@@ -0,0 +1,15 @@
+module OpenApiAnnotator
+  class SpecBuilder
+    def build(info:)
+      paths = PathsBuilder.new.build
+      components = ComponentsBuilder.new.build
+
+      OpenApi::Specification.new(
+        openapi: "3.0.1",
+        info: info,
+        paths: paths,
+        components: components,
+      )
+    end
+  end
+end

data/lib/open_api_annotator/type_validator.rb

@@ -0,0 +1,36 @@
+module OpenApiAnnotator
+  class TypeValidator
+    def validate!(type)
+      if type.is_a?(Array)
+        validate_as_collection_resource!(type)
+      else
+        validate_as_single_resource!(type)
+      end
+    end
+
+    private
+
+    def validate_as_collection_resource!(type)
+      unless type.size == 1
+        raise ValidationError, "type array should have one element, but it has #{type.size}."
+      end
+
+      validate_as_single_resource!(type[0])
+    end
+
+    def validate_as_single_resource!(type)
+      case type
+      when Symbol
+        unless type.in?(OpenApi::DataTypes.all_types)
+          raise ValidationError, "type should be a symbol of: #{OpenApi::DataTypes.all_types.join(", ")}, but got #{type}."
+        end
+      when Class
+        # pass
+      when NilClass
+        raise ValidationError, "type should not be nil."
+      else
+        raise ValidationError, "type is unexpected class #{type.class}."
+      end
+    end
+  end
+end

data/lib/open_api_annotator/version.rb

@@ -0,0 +1,3 @@
+module OpenApiAnnotator
+  VERSION = "0.1.0"
+end

data/lib/tasks/api_spec.rake

@@ -0,0 +1,12 @@
+namespace :api_spec do
+  desc 'Create OpenAPI Specification'
+  task :create => :environment do
+    puts "Creating..."
+    OpenApiAnnotator.create_spec_yaml
+    puts "Created.✨"
+  end
+end
+
+task :api_spec do
+  Rake::Task["api_spec:create"].invoke
+end

data/open_api_annotator.gemspec

@@ -0,0 +1,37 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "open_api_annotator/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "open_api_annotator"
+  spec.version       = OpenApiAnnotator::VERSION
+  spec.authors       = ["Kent Nagata"]
+  spec.email         = ["ngtknt@me.com"]
+
+  spec.summary       = %q{OpenApi spec generation by bottom-up.}
+  spec.description   = %q{OpenApiAnnotator realizes to generate OpenApi spec by annotating to Controller and ActiveModelSerializer.}
+  spec.homepage      = "https://github.com/ngtk/open_api_annotator"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "open_api", ">= 0.3.3"
+  spec.add_dependency "active_model_serializers", "~> 0.10.0"
+
+  rails_versions = ['>= 4.1', '< 6']
+  spec.add_dependency "actionpack", rails_versions
+  spec.add_dependency "railties", rails_versions
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "bump"
+end

metadata

@@ -0,0 +1,227 @@
+--- !ruby/object:Gem::Specification
+name: open_api_annotator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kent Nagata
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: open_api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.3
+- !ruby/object:Gem::Dependency
+  name: active_model_serializers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bump
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: OpenApiAnnotator realizes to generate OpenApi spec by annotating to Controller
+  and ActiveModelSerializer.
+email:
+- ngtknt@me.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/open_api_annotator.rb
+- lib/open_api_annotator/association.rb
+- lib/open_api_annotator/attribute.rb
+- lib/open_api_annotator/components_builder.rb
+- lib/open_api_annotator/config.rb
+- lib/open_api_annotator/configurable.rb
+- lib/open_api_annotator/controller_annotatable.rb
+- lib/open_api_annotator/errors.rb
+- lib/open_api_annotator/field.rb
+- lib/open_api_annotator/format_validator.rb
+- lib/open_api_annotator/nullable_validator.rb
+- lib/open_api_annotator/paths_builder.rb
+- lib/open_api_annotator/serializer_annotatable.rb
+- lib/open_api_annotator/spec_builder.rb
+- lib/open_api_annotator/type_validator.rb
+- lib/open_api_annotator/version.rb
+- lib/tasks/api_spec.rake
+- open_api_annotator.gemspec
+homepage: https://github.com/ngtk/open_api_annotator
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: OpenApi spec generation by bottom-up.
+test_files: []