Apidoc

Capfile

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'pry'
+
 # Load DSL and set up stages
 require 'capistrano/setup'
 
@@ -38,6 +40,7 @@ install_plugin Capistrano::SCM::Git
 # Add the mixin method
 $:.unshift(File.dirname(__FILE__))
 require 'lib/mixin'
+require 'lib/popen'
 
 # Disable freezing rake tasks
 require 'lib/disable_immutable_task'

Gemfile

@@ -2,6 +2,11 @@
 
 source 'https://rubygems.org'
 
+gem 'pry', '~> 0.10.4'
+
 gem 'capistrano', '~> 3.8.2'
 gem 'capistrano-rails', '~> 1.3.0'
 gem 'capistrano-rbenv', '~> 2.1.1'
+
+gem 'graphql-docs', github: 'eugenk/graphql-docs',
+                    branch: 'improve_style_and_fix_nil_fields'

Gemfile.lock

@@ -1,6 +1,25 @@
+GIT
+  remote: git://github.com/eugenk/graphql-docs.git
+  revision: cc3eedee1ea10027c35fad251aa6e9ddc9bdd19d
+  branch: improve_style_and_fix_nil_fields
+  specs:
+    graphql-docs (0.6.2)
+      commonmarker (~> 0.16)
+      extended-markdown-filter (~> 0.4)
+      faraday (< 0.10)
+      gemoji (= 2.1.0)
+      graphql (~> 1.4)
+      html-pipeline (~> 2.2)
+      sass (~> 3.4)
+
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (5.1.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
     airbrussh (1.3.0)
       sshkit (>= 1.6.1, != 1.7.0)
     capistrano (3.8.2)
@@ -17,14 +36,53 @@ GEM
     capistrano-rbenv (2.1.1)
       capistrano (~> 3.1)
       sshkit (~> 1.3)
+    coderay (1.1.1)
+    commonmarker (0.16.8)
+      ruby-enum (~> 0.5)
+    concurrent-ruby (1.0.5)
+    extended-markdown-filter (0.4.9)
+      html-pipeline (~> 2.0)
+      nokogiri (~> 1.6)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.9.18)
+    gemoji (2.1.0)
+    graphql (1.6.6)
+    html-pipeline (2.6.0)
+      activesupport (>= 2)
+      nokogiri (>= 1.4)
     i18n (0.8.4)
+    method_source (0.8.2)
+    mini_portile2 (2.2.0)
+    minitest (5.10.2)
+    multipart-post (2.0.0)
     net-scp (1.2.1)
       net-ssh (>= 2.6.5)
     net-ssh (4.1.0)
+    nokogiri (1.8.0)
+      mini_portile2 (~> 2.2.0)
+    pry (0.10.4)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
     rake (12.0.0)
+    rb-fsevent (0.10.2)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    ruby-enum (0.7.1)
+      i18n
+    sass (3.5.1)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    slop (3.6.0)
     sshkit (1.13.1)
       net-scp (>= 1.1.2)
       net-ssh (>= 2.8.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.3)
+      thread_safe (~> 0.1)
 
 PLATFORMS
   ruby
@@ -33,6 +91,8 @@ DEPENDENCIES
   capistrano (~> 3.8.2)
   capistrano-rails (~> 1.3.0)
   capistrano-rbenv (~> 2.1.1)
+  graphql-docs!
+  pry (~> 0.10.4)
 
 BUNDLED WITH
    1.14.6

Readme.md

@@ -15,9 +15,10 @@ where the three place holders can be:
   * `live` (ontohub.org)
   * `staging` (staging.ontohub.org)
 * `<application>` is one of
-  * `ontohub-frontend`
-  * `ontohub-backend`
-  * `hets-rabbitmq-wrapper`
+  * `apidoc`: The API documentation of the backend
+  * `ontohub-backend`: The backend
+  * `ontohub-frontend`: The frontend
+  * `hets-rabbitmq-wrapper`: The HetsRabbitMQWrapper
 
 so to deploy the backend to staging.ontohub.org, you need to execute
 

config/deploy/staging_apidoc.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+mixin 'servers/staging.ontohub.org'
+mixin 'environments/production'
+mixin 'applications/apidoc'

config/mixins/applications/apidoc.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'graphql-docs'
+
+Rake::Task['load:defaults'].invoke
+Rake::Task['load:defaults'].clear
+Rake::Task['load:defaults'].reenable
+Rake::Task['load:defaults'].invoke
+
+set :application, 'apidoc'
+set :repo_url, 'https://github.com/ontohub/ontohub-backend.git'
+
+mixin('local_repository')
+
+set :graphql_base_url, '/graphql'
+
+# rubocop:disable Metrics/BlockLength
+before :'deploy:publishing', :build_application do
+  # rubocop:enable Metrics/BlockLength
+  run_locally do
+    Bundler.with_clean_env do
+      local_repo = fetch(:local_repo_path)
+      build_dir = File.join(local_repo, 'build')
+      Dir.chdir(local_repo) do
+        system('bundle install')
+
+        # Build the REST API documentation into a temp directory
+        system('bundle exec rails apidoc:prepare')
+        system('bundle exec rails apidoc:init')
+        Dir.chdir('apidoc') do
+          system('yarn build')
+        end
+
+        # Build the GraphQL documentation into a temp directory
+        apidoc_graphql_dir = File.join(local_repo, 'apidoc-graphql')
+        graphql_schema_file = File.join(local_repo, 'tmp/graphql_schema.json')
+
+        popen({'FILE' => graphql_schema_file},
+              'bundle', 'exec', 'rails', 'graphql:write_json')
+
+        GraphQLDocs.build(delete_output: true,
+                          output_dir: apidoc_graphql_dir,
+                          base_url: fetch(:graphql_base_url),
+                          path: graphql_schema_file)
+
+        # Move the generated documentation files to the `build` directory
+        FileUtils.rm_rf(build_dir)
+        system("mkdir -p #{build_dir}")
+        FileUtils.mv(File.join(local_repo, 'apidoc/build'),
+                     File.join(build_dir, 'rest'))
+        FileUtils.mv(apidoc_graphql_dir, File.join(build_dir, 'graphql'))
+
+        # Add an index page to select the API docs:
+        index_content = <<~INDEX
+          <html>
+            <head>
+              <title>Ontohub API Documentation</title>
+            </head>
+            <body>
+              <h1>Ontohub API Documentation</h1>
+              <p>Please select an API</p>
+              <ul>
+                <li><a href="graphql">GraphQL</a> (with full functionality)</li>
+                <li><a href="rest">REST</a> (read only actions)</li>
+              </ul>
+            </body>
+          </html>
+        INDEX
+        File.write(File.join(build_dir, 'index.html'), index_content)
+      end
+    end
+  end
+end
+
+after :build_application, :publish_built_application

config/mixins/applications/hets-rabbitmq-wrapper.rb

@@ -2,25 +2,17 @@
 
 Rake::Task['load:defaults'].invoke
 Rake::Task['load:defaults'].clear
-require 'capistrano/rbenv'
-require 'capistrano/bundler'
+mixin('ruby_project_requirements')
 Rake::Task['load:defaults'].reenable
 Rake::Task['load:defaults'].invoke
 
 set :application, 'hets-rabbitmq-wrapper'
 set :repo_url, 'https://github.com/ontohub/hets-rabbitmq-wrapper.git'
 
+mixin('ruby_project_config')
+
 # Default value for :linked_files is []
 # append :linked_files, 'config/settings.yml'
 
 # Default value for linked_dirs is []
 # append :linked_dirs, 'log'
-
-set :rbenv_type, :system # or :user
-set :rbenv_ruby, File.read('.ruby-version').strip
-set :rbenv_prefix, "RBENV_ROOT=#{fetch(:rbenv_path)} "\
-                   "RBENV_VERSION=#{fetch(:rbenv_ruby)} "\
-                   "#{fetch(:rbenv_path)}/bin/rbenv exec"
-set :rbenv_map_bins, %w(rake gem bundle ruby)
-
-set :bundle_binstubs, -> { shared_path.join('bin') }

config/mixins/applications/ontohub-backend.rb

@@ -2,15 +2,16 @@
 
 Rake::Task['load:defaults'].invoke
 Rake::Task['load:defaults'].clear
-require 'capistrano/rbenv'
-require 'capistrano/bundler'
+mixin('ruby_project_requirements')
 require 'capistrano/rails/migrations'
 Rake::Task['load:defaults'].reenable
 Rake::Task['load:defaults'].invoke
 
 set :application, 'ontohub-backend'
 set :repo_url, 'https://github.com/ontohub/ontohub-backend.git'
 
+mixin('ruby_project_config')
+
 # Default value for :linked_files is []
 append :linked_files, 'config/database.yml',
                       'config/secrets.yml',
@@ -23,16 +24,6 @@
                      'tmp/cache', 'tmp/pids', 'tmp/sockets',
                      'vendor/bundle'
 
-set :rbenv_type, :system # or :user
-# The ruby version is only considered if there is no override (like a
-# .ruby-version file)
-set :rbenv_ruby, '2.4.1'
-set :rbenv_prefix, "RBENV_ROOT=#{fetch(:rbenv_path)} "\
-                   "#{fetch(:rbenv_path)}/bin/rbenv exec"
-set :rbenv_map_bins, %w(rake gem bundle ruby rails)
-
-set :bundle_binstubs, -> { "~#{fetch(:deploy_user)}/bin" }
-
 set :migration_role, :app
 
 after :'deploy:updated', :'version:fetch' do